Case Header object

Info

This article describes an object that is a key element of requests in communication with the database via SOAP and REST services. The CaseHeader header is necessary for implementing case update tasks in the database, supports the identification and update of the case type definition. This object contains predefined fields of the Case entity, which are used to identify the case, its status and other important information. The article also presents examples of case header construction in various formats (XML and JSON) and discusses the meaning of individual fields.

Definition of the CaseHeader object


Layers in which used	Business
Type	Business object
Java interface	IMrcCaseHeader, IMrcObject, ICaseHeader
className/type	`MrcCaseHeader`
Java implementation	`pro.ibpm.mercury.business.data.api.MrcCaseHeader`
DTO implementation	`pro.ibpm.mercury.business.data.api.CaseHeader`
XML definition	hgdb-mrc-object-3.0.xsd

Case header. A business object representing predefined (constant) fields of the Case entity and fields optimizing case type identification. It is the basis for verifying the uniqueness of the case and identifying the MRC universal object as an object describing the case (see Case as MRC universal objects).

List and meaning of individual fields/parameters

Parameters	Description	Type/Attribute "type"	Required	Allowed values
caseId	Representation of the predefined `Case` entity field. Case identifier	`Long`/`Integer`	No/Yes¹
bpmProcessId	Representation of the predefined `Case` entity field. BPM process instance identifier to which the case is associated.	`Long`/`Integer`	No
inventoryCode	Representation of the predefined `Case` entity field. Generated/unique case code	`String`/`String`	No
groupId	Representation of the predefined `Case` entity field. Case group identifier.	`Long`/`Integer`	No/Yes¹	Existing group identifier
typeId	Representation of the predefined `Case` entity field. Type identifier	`Long`/`Integer`	No/Yes¹	Existing case type version identifier
typeCode	Case type code	`String`/`String`	Yes
endDate	Representation of the predefined `Case` entity field. Case handling/completion date from the BPM process perspective	`CaseDate`/`Date`	No
dueDate	Representation of the predefined `Case` entity field. Planned case handling/completion date from the BPM process perspective	`CaseDate`/`Date`	No
status	Representation of the predefined `Case` entity field. Current status of the case. Case statuses are derived from the process nature of the case object and are related to whether the bpmProcessId field is set: `N` - means that the case was processed by the process with the given id, currently it also means that it can be used by another process: `A` - means that the case is being processed by the process with the given id, but in the world of dictionaries it can also mean usable data (when bpmProcessId is not set) `O` - means that the execution of the process instance with the given id has been "postponed" until later `Z` - means interruption/cancellation of the associated process, it also means that the case should not be used in processes, it must not be edited (an attempt to change it will end with an exception). Most often the `Z` status is set when the case type changes. Old, unchangeable version of the case.	`String`/`String`	No/Yes¹	`A`(Active) `N`(Completed) `O`(Postponed) `Z`(Interrupted)
piervousVersionId	Representation of the predefined field of the `Case` entity. When changing the case type, a new case (new version of the case) is automatically created. The case in the previous type is interrupted (its status receives the Z flag) and the new case is marked as active (flag A). The field contains the value of the closed case identifier, which is the prototype of the current one. The field is filled in automatically or manually - see the article Case versions	`Long`/`Integer`	No
rootVersionId	Representation of the predefined field of the `Case` entity. The field contains an indication of the case, which is the main version of the case (original). The field is filled in automatically or manually - see the article Case versions	`Long`/`Integer`	No
priceValue	Representation of the predefined field of the `Case` entity. Case value, price	Double/Decimal	No
priceValueCode	Representation of the predefined field of the `Case` entity. 3-letter currency code in which the case value is expressed.	`String`/`String`	No	Examples of codes: `PLN`, `EUR`, etc.
priceExchangeDate	Representation of the predefined field of the `Case` entity. Date of the exchange rate, used to convert the price value when the currency code is different from the system one.	`CaseDate`/`Date`	No
storeCount	Representation of the predefined field of the `Case` entity. Number of cases in stock (not assigned to any user). User assignment is done via the GroupCase entity.	`Integer`/`Integer`	No
storeId	Representation of the predefined `Case` entity field. The identifier of the case's native storage. Creating a case requires that it be assigned to a storage.	`Long`/`Integer`	No/Yes¹
createDate	Representation of the predefined `Case` entity field. Date the case was created	`CaseDate`/`Date`	No
createdBy	Representation of the predefined `Case` entity field. Name of the creating user	`String`/`String`	No
lastModifyDate	Representation of the predefined `Case` entity field. Date the case data was modified	`CaseDate`/`Date`	No
lastModifiedBy	Representation of the predefined `Case` entity field. Name of the modifying user	`String`/`String`	No
modifyComment	Representation of the predefined `Case` entity field. Last comment of the case data change. Field filled in automatically based on context data (comment) sent during the update/adding of the case.	`String`/`String`	No
createdByRoleName	Representation of the predefined field of the `Case` entity. Name of the role the user held during the case addition operation. Field filled in automatically based on context data (currentRole) sent when adding a case.	`String`/`String`	No
lastModifiedByRoleName	Representation of the predefined `Case` entity field. Name of the role the user held during the case update operation. Field filled in automatically based on context data (currentRole) sent when updating the case.	`String`/`String`	No
subCaseReferenceId	If the object occurs as a dependent case (an element of a parent case), this field contains the identifier of the reference defining this dependency (this association).	`Long`/`Integer`	No
className	Name of the class/type of the complex object represented by the case. Name of the case type version.	`String`/`String`	No
version	System number of the last change/version of the case	`String`/`String`	No
dirty	Control flag with information whether the sent case should be updated during the modification action. Important for complex cases, e.g. not to update dependent cases when updating the parameters of the parent case and vice versa, when we want to update the parameters of the child case without registering changes in the parent case.	`Boolean`/`Boolean`	Yes	`true` or `false`
pkPropertyName	Name of the case parameter, which is a unique value.	`String`/`String`	No
headerMetadata	The CaseHeader object inherits some fields from the MrcObject object (see Universal MRC objects). Additional information related to the sent object, such as status.	`MrcObjectMetadata`	No

To properly explain the meaning of the CaseHeader object (and its fields), we will try to present and describe specific examples.

Basic examples of use

Below are examples of defining the case header in business services. Let's recall the Case vs. object, the IBM BPM system business object analyzed in the article. Definition of the sample business object TestMrcObject:

Definition of the sample business object TestMrcObject

Preparing data in the system, without defining the case primary key field

Let's define the case header for the insert action into the system. Let's build a CaseHeader object for an example case according to the following guidelines:

⬜ caseId – empty, we don't know the case ID yet
✅️ – if we know the process instance ID, we set it to e.g. 1234
⬜ inventoryCode – empty, the value will be generated (provided that there is a code generator in the system)
✅️ groupId – if we know the group ID to which the current case is to be assigned, we set it
⬜ typeId – we don't know the case type ID – we leave it empty
✅️ typeCode – we know the type code – this is the name of the business object (most often), unless we decide otherwise. We assume the value of ‘TestMrcObject’
⬜ endDate – set the appropriate value (can be empty)
⬜ dueDate - set the appropriate value (can be empty)
✅️ status – set the value of A – the case should be active
⬜ piervousVersionId – empty, the value will be set automatically if necessary
⬜ rootVersionId - empty, the value will be set automatically if necessary
⬜ priceValue - set the appropriate value (can be 0) or leave it empty
⬜ priceValueCode – set the appropriate value (can be empty) – then the system code will be assumed. - ⬜ priceExchangeRate - set the appropriate value different from 0 (can be 1)
✅️ storeCount - set the appropriate value different from 0 (can be 1)
✅️ storeId - if we know the case warehouse to which the current case is to be assigned, set it
⬜ fields createDate, createdBy, lastModifyDate, lastModifiedBy, modifyComment, createdByRoleName, lastModifiedByRoleName are fields updated automatically based on the Context object
⬜ subCaseReferenceId - the TestMrcObject case is a superior case - do not set it!
✅️ className – we do not know the case type identifier – the class name (object name) will be the basis for identifying the type (or creating a new one with a given name). The business object is called TestMrcObject, so we enter this value. - ✅️ objectID – we set the external identifier of the object type version, based on which a specific version of the case type will be created. We may not know it, but we can always define it in some way, e.g. TestMrcObject.1 – it is important that when we use this object, with such a definition, we should always use the same value – this will support/speed up the identification of the case type by the Mercury system. In the IBM BPM system, we can extract this identifier based on the definition of the business object class. Let's assume that this is the value 5a2eed95-5975-42ff-8c4a-1527f38266fb and we will set it like this
✅️ rootVersionContextID – we set the external context identifier that is to initialize a given version of the case type. It is possible that we do not know it, but we can always define it in some way, e.g. App.1 – it is important that when we use this object in a given application, we always use the same value – this will support/speed up the identification of the case type by the Mercury system. In the IBM BPM system, we can use the snapshot identifier (state image) of the process application from which the business object comes. Let's assume that this is the value 2064.895ead8d-6fab-4eb8-b54b-b94cd07bb548T.
⬜ version – when inserted for the first time, we leave it empty.
✅️ dirty – when modifying (adding) an object, the flag should be set to "true"
⬜ pkPropertyName – let's leave it blank. The next example will show the purpose of using this field.

The construction of the header of a case represented as an ANY type

The case header is used in methods that require different formats. In the case of SOAP business methods that support arguments of any type (ANY XML), it is recommended that each TAG of the sent object has the type attribute set with the name of the field type (this makes it easier to identify the field type). In this case, the values are predefined (see the table with the list of fields, and the corresponding method descriptions). The values defined earlier will give us the following sample XML that should be used during the first insert. In the case of REST services, where it is not possible to send the type of the field, the values will be the same, but without this information:

XML for SOAP insertion service
JSON for REST insertion service

<mrcCaseHeader type="MrcCaseHeader" xmlns="http://business.dto.ws.hgdb.io/mrcObject" 
   xsi:schemaLocation="http://business.dto.ws.hgdb.io/mrcObject http://hgdb.io/xsd/dto/hgdb-mrc-object-3.0.xsd" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <bpmProcessId type="Integer">1234</bpmProcessId>
 <groupId type="Integer">1001</groupId>
 <typeCode type="String">TestMrcObject</typeCode>
 <status type="String">A</status>
 <storeCount type="Integer">1</storeCount>
 <storeId type="Integer">1001</storeId>
 <className type="String">TestMrcObject</className>
 <objectID type="String">5a2eed95-5975-42ff-8c4a-1527f38266fb</objectID>
 <rootVersionContextID type="String">2064.895ead8d-6fab-4eb8-b54b-b94cd07bb548T</rootVersionContextID>
 <dirty type="Boolean">true</dirty>
</mrcCaseHeader>

{
  "bpmProcessId": 1234,
  "groupId": 1001,
  "typeCode": "TestMrcObject",
  "status": "A",
  "storeCount": 1,
  "storeId": 1001,
  "className": "TestMrcObject",
  "objectID": "5a2eed95-5975-42ff-8c4a-1527f38266fb",
  "rootVersionContextID": "2064.895ead8d-6fab-4eb8-b54b-b94cd07bb548T",
  "dirty": true
}

After executing the case insertion request using the SOAP (XML) service, in the service response, we will receive the completed header of the freshly created case (it is assigned to the field named mrcCaseHeader of the case):

Header in the insertion request response

The values that were automatically completed after the successful case save operation have been marked in red. As we can see, the case identifier (the caseId field) has been completed and the identifier of the identified case type version has been set. The header constructed in this way should be used in case update services. Remember to set the value of the dirty field to true for the update to take place. We also modify the header if we want to change other predefined case fields.

Date type field

Date type field problem. It is important that the date fields are sent in the appropriate format. The default format is yyyy/MM/dd HH:mm:ss.SS z, but it can be changed by setting the formats field in the context object appropriately (see the description of the Context object). If the date is sent in a specific format, the attribute isEncoded="false" should be set

<createDate isEncoded="false" type="Date">2017/06/03 00:44:12.958 CEST</createDate>

If we set isEncoded="true" the date should be sent as a number of milliseconds (https://currentmillis.com/):

<createDate isEncoded="true" type="Date">1498031451441</createDate>

Preparing data in the system, with the definition of the case's primary key field

An example could be integration with a system that has a data set and an established relational model, and has its own field that uniquely identifies the case. Mercury DB has its own unique identifier, this is the value of the caseId header field. We do not want the data to be duplicated on the case database side. We also want this field to be unique in Mercury DB. Let's create a case header for such a case called TestUser:

⬜ caseId – empty, we don't know it yet and unfortunately we won't be able to use it
⬜ bpmProcessId – empty, the action has no connection with the BPM process
⬜ inventoryCode – empty, the value will be generated (provided that a code generator exists in the system)
⬜ groupId – if we know the group identifier – leave it empty
⬜ typeId – we don't know the case type identifier – leave it empty
✅️ typeCode – we know the type code – this is the name of the business object (most often), unless we decide otherwise. We assume the value ‘TestUser’
⬜ endDate – set the appropriate value (can be empty)
⬜ dueDate – set the appropriate value (can be empty)
✅️ status – set the value “A” – the case should be active
⬜ piervousVersionId – empty, the value will be set automatically if necessary
⬜ priceValue - set the appropriate value (can be 0) or leave it empty
⬜ priceValueCode – set the appropriate value (can be empty) – then the system code will be assumed. - ⬜ priceExchangeRate - set the appropriate value different from 0 (can be 1)
✅️ storeCount - set the appropriate value different from 0 (can be 1)
⬜ storeId - if we know the case warehouse to which the current case is to be assigned, set it
⬜ fields createDate, createdBy, lastModifyDate, lastModifiedBy, modifyComment, createdByRoleName, lastModifiedByRoleName are fields updated automatically based on the Context object
⬜ subCaseReferenceId - the TestUser case in this case is a standalone case - we do not set it!
✅️ className – we don't know the case type identifier – the class name (object name) will be the basis for identifying the type (or creating a new one with a given name). The business object is called TestUser, so we enter this value.
✅️ objectID – we set the external identifier of the object type version, based on which a specific version of the case type will be created. We may not know it, but we can always define it in some way, e.g. TestUser.1 – it is important that when we use this object, with such a definition, we should always use the same value – this will support/speed up the identification of the case type by the Mercury system.
✅️ rootVersionContextID – we set the external identifier of the context, which is to initialize a given version of the case type. It is possible that we do not know it, but we can always define it in some way, e.g. App.1 – it is important that when we use this object in a given application, we always use the same value – this will support/speed up the identification of the case type by the Mercury system.
⬜ version – when inserting it for the first time, we leave it empty.
✅️ dirty – when modifying (adding) an object, the flag should be set to true
✅️ pkPropertyName – the case type TestUser has its own, unique field called id – let's assign this value to this field. We can define a composite key represented by the formula list of parameters separated by the concatenation operator || e.g. field1||field2

Construction of a case header represented as ANY

The values defined earlier will give us the following example header to use when inserting for the first time:

XML dla usługi wstawiania SOAP
JSON dla usługi wstawiania REST

<mrcCaseHeader type="MrcCaseHeader" xmlns="http://business.dto.ws.hgdb.io/mrcObject" 
   xsi:schemaLocation="http://business.dto.ws.hgdb.io/mrcObject http://hgdb.io/xsd/dto/hgdb-mrc-object-3.0.xsd" 
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 <typeCode type="String">TestUser</typeCode>
 <status type="String">A</status>
 <storeCount type="Integer">1</storeCount>
 <className type="String">TestUser</className>
 <objectID type="String">TestUser.1</objectID>
 <rootVersionContextID type="String">App.1</rootVersionContextID>
 <dirty type="Boolean">true</dirty>
 <pkPropertyName type="String">id</pkPropertyName>
</mrcCaseHeader>

{
  "typeCode": "TestUser",
  "status": "A",
  "storeCount": 1,
  "className": "TestUser",
  "objectID": "TestUser.1",
  "rootVersionContextID": "App.1",
  "dirty": true,
  "pkPropertyName": "id"
}

Header in the insertion request response

The values that were automatically completed after the successful case save operation have been marked in red. We also did not provide the group identifier (groupId) - the group was assigned automatically.

We can skip all the fields added in the subsequent update actions by using the static header that we defined during the first insertion. However, I would like to point out that the Mercury DB system identified the case type and assigned it an identifier, which can be found in the typeId field. The store was also assigned automatically - see the storeId field. These are very important case parameters and providing their values when adding and updating subsequent cases speeds up the save action. It is recommended to set these values to a fixed value in this case, for each subsequent case save action.

The Mercury DB system will try to identify an existing case of a given type based on the value of the field named id and if it succeeds, it will update the data, not create a duplicate.

Summary

Based on the examples, we can see that the case header is an important element of identifying an existing case in the Mercury DB system.

Its appropriate parameters not only indicate an existing case in the database, but also support the process of identifying the case type. Defining the case type version is influenced not only by the list of fields attached to the case. The version change is affected by changes to the following header fields:

typeCode – change of type code
className – change of type version name
objectID – change of external object type version identifier, based on which a specific case type version will be created
rootVersionContextID – change of external context identifier, which is to initialize a given case type version
pkPropertyName – change of unique field

Analyzing examples and being aware of the importance of the header in identifying case type versions, it is recommended that development teams building integrations with different systems communicate on common solutions. Assuming a scenario in which a business object named TestMrcObject created in the system contains an object named TestUser and another "external system" is integrated with the Mercury DB database, the development team should add the pkPropertyName field with the id value to "their" TestUser case header, and the list of fields should be consistent with the object coming from the "external system".

No/Yes - required field value means that the parameter is required during the case update action. ↩ ↩² ↩³ ↩⁴ ↩⁵

Definition of the CaseHeader object​

Basic examples of use​

Preparing data in the system, without defining the case primary key field​

The construction of the header of a case represented as an ANY type​

Preparing data in the system, with the definition of the case's primary key field​

Construction of a case header represented as ANY​

Summary​

Footnotes​