Business entities

Business Entities

Business entities are functional representations of the raw data from the ConnectPlaza Analyze database. These messages will be processed as they are running through the system. This means that the data will be available after the business entity is created. There is no possibility to recreate this data from the historic data.

What do we mean by a functional representation of the data. For example, we receive messages like the next example:

<?xml version="1.0" encoding="UTF-8" ?>
<Customers>
	<Customer>
		<first_name>Edward</first_name>
		<last_name>Evans</last_name>
		<full_name>Edward Evans</full_name>
		<phone>503-310-3671</phone>
		<address>1 A ST</address>
		<city>JOHNSTON</city>
		<filenumber>764453213</filenumber>
	</Customer>
</Customers>

One of the questions which could be asked to you is for instance: "Is file number 764453213" filed in the system?" . If you have only the message available, this will be a problem. You have to open the messages and look at the message to find out if this file number has been send to the system. You can imagine how difficult this must be, if the messages are very big and you have a lot of them. This is where the business entities come in. As the messages are processed, we will extract the functional data from it and sent it to the database, so that we can search for the requested data, in this case file numbers.

Creating a new business entity

To go to the business entities, select the type . If you started the business entities for the first time, you will see the following screen:

The following data is presented to you:

Field	Description
ID	Every message has a correlation ID given to it by the system. This is its ID.
Timestamp	Date-Timestamp the record is registered.
Interface	Interface where the wiretap is located. This can be, for example, consumer, service or producer. But you can also define a value yourself in the Analyze wiretap. Then you will see this value here.
Flow	Flow name, or the given value in accordance with the Analyze wiretap in your interface.
Component	Presentation of the component given in the Analyze Wiretap during configuration of the Analyze wiretap in the constructor.

To create a new business entity you press the button, in the business entity section. The next screen will be presented to you:

First, we must name the business entity. This can be any name, it is just an identification for this business entity. As we want to know what this entity represents, choose a name which suits the purpose of this business entity. For this example we will create a business entity to check the file numbers. We will add the full name of the customer to the business entity for reference. This will look like this:

Press to save the selection. After saving this business entity and selecting the business entity, the overview screen will change to represent the correct data.

As you can see, the newly created fields are added to the overview and to the filter options. You can use them as described with the messages / flows.

Before we enter the data needed for selecting the correct functional data, we open a Flow and put it on a separate tab, or in a separate window. You can do that by pressing the button. A new tab in your browser will open with the selected detailed information.

Now that we have the fields that we want to see in our business entity, we have to define the rules for them. To do that, we edit the business entity by pressing the button. The next screen will open:

You see that there is a new button, . Press this button and we enter the Rules manager.

As this is the first time we see the Rules manager, it is empty. We now have to define the matches or links from the data we have and the data we want to present in the overview, in our case the file number and the full name of the customer.

To create a new Match entry, press the button and the following screen will open for you:

Now you have to add the position from where you want to select the data. In our case this will be the first Analyze wiretap. Fill in the fields and press the button. You can verify the selection in the flow detail screen, which we opened in a different tab (see above). After adding the rule, it will turn up at the upper left of the screen, like this:

Now we have the section where we want to get the data from. But there could be a lot of different messages send over this entry point. We could, for instance, put an Analyze wiretap after a webservice call. This webservice call returns the answer to our request. But this response could be an error message as well.

The next step in defining the correct data is to set an Identify Rule. This rule is mandatory. It can be a simple rule like the following XPATH expression: count(/Customers/Customer)>1 or something more complicated. The rule is to make sure we have the correct message to get the data from. Open the Match entry via the button, the following screen will be shown to you.

We enter the following information as the Identify Rule:

You have just identified the message. How? Well you selected the message and you checked if /Customers/Customer was available in this message. If you used the XPATH helper, you would find out that the value, running this function on a correct message, was true.

Now that we have the correct message identified we need to add the Attribute Rules. With these lines we select the data out of the message and bind it to the defined fields. This looks like this:

After entering the Attribute Rules, do not forget to press the to save the rule set. And close the screens until you are in the Business entities overview.

Now, we will put the demo files in our in directory, to be processed. We have 4 customer files as described above, with different names and file numbers. Let us see what has happened after we processed the messages. It can take up to 1 minute after reading the messages to see them in this overview. This is because the rule engine runs once a minute. This is a separate process.

As you can see, we added 4 messages. One of them was Edward Evans with filenumber 764453213. You see the Full Name and the File number fields with the correct values. You can also search within these fields with the Filter options. This is what makes Analyze a very important tool to use.

Repeated Rules

For the next example we want to process a different message. This message has some of the same values as described above, but has more than 1 nodes. It looks like this:

<?xml version="1.0" encoding="UTF-8" ?>
<Customers>
    <Customer>
        <first_name>Gerald</first_name>
        <last_name>Davourds</last_name>
        <full_name>Gerald Davourds</full_name>
        <filenumber>3423342342342</filenumber>
    </Customer>
    <Customer>
        <first_name>Jan</first_name>
        <last_name>van Hoek</last_name>
        <full_name>Jan van Hoek</full_name>
        <filenumber>8677746655</filenumber>
    </Customer>
    <Customer>
        <first_name>Judith</first_name>
        <last_name>Hanen</last_name>
        <full_name>Judith Hanen</full_name>
        <filenumber>4598359375</filenumber>
    </Customer>
    <Customer>
        <first_name>Peter</first_name>
        <last_name>Toepuater</last_name>
        <full_name>Peter Toepuater</full_name>
        <filenumber>0384503850384</filenumber>
    </Customer>
</Customers>

To process this message, we use the interface below.

Just a simple File Pickup an Analyze wiretap and a File Drop.

We want to use the same business entity, because we want to have the file number and the full name, but we are going to use a different rule set. So we open the Rules manager for File numbers (Edit Business Entity --> Rules)

Press the button to add a new Match entry, which looks like this:

Add the next Identify rule:

As you can see we added the Repeat Rule. This rule selects all the nodes you want to have from the message. In this case our target will be Customer, and within the customer we define the two Attribute rules, File number and Full Name.

ATTENTION: Check the attribute rules!

There is NO forward slash at the front of the expression
Always convert the XPATH expression to Text by adding /text() behind the XPATH query
Use Reference = empty to select all of the entries. A common mistake is to put 0 as a reference, which will result in a number of the same references (as 0 is entity 1 of the XML in our case)

Now we put through our message and check the result:

You can double click on any of the messages to get some detailed information about this message. The following screen will pop up:

Double click on the message again, and you will get more detailed information.

Example of Mapping JSON to a Business Entity

In this example we will walk you through setting up a business entity mapping based on JSON messages. The JSON messages are sent in a POST operation to a REST listener after which they are immediately picked up by an Analyze Wiretap as depicted in the following flow diagram:

The JSON messages in this example will have the following structure:

We want to create a book business entity that has fields category, author, title, isbn and price. As you can see in the above example a single message can contain multiple books. So once we have set up our mapping, a single message can yield multiple book business entity instances.

The first step in setting up this mapping is adding a new business entity and adding the fields:

After saving the business entity we can start adding rules by clicking on the rules button. Please note you might have to first select the Wiretap associated with this mapping by adding a match entry (in our example this is the Wiretap found in test-interface>test-flow>Consumer). We can now define the mapping rules:

The rules are defined using JSON-Path. For the identify rule we use $.store.book. This matches messages that contain a JSON object in which the root object (in JSON-Path this is denoted by $) has a store attribute which in turn has a book attribute. A message that satisfies this rule is a candidate for this mapping.

Since there is a one-to-many relationship between a single message and book business entity instances, we need a repeat rule. The rule $.store.book[*] selects the elements of the book array. Note that $.store.book (without the [*]) does not work because this would select a single element, i.e. the book array, instead of the individual book elements in the array.

The attribute rules are mostly straightforward. However, please note that since we are using a repeat rule the actual JSON object against which the attribute's JSON-Path expression is matched is different from the original JSON object. For example, the category attribute has JSON-Path expression $.category as the mapping rule. This matches the category field of the root object (remember that $ corresponds to the root JSON object). While this would not match anything in the original complete JSON object, it does match the JSON objects we have selected using the repeat rule, i.e. the individual JSON objects in the book array.

This completes the mapping from JSON to the book business entity. After sending a single message to our flow containing our example JSON we obtain the following result:

A single message has yielded 4 book business entity instances. Note that the ISBN field is empty for some entries because the original JSON object did not define an ISBN.

JSON-Path expressions also allow us to do some rudimentary filtering. For example, suppose we are only interested in mapping books with a price greater than 10. We can change the repeat rule for the book business entity from $.store.book[*] to the following:

We are using the repeat rule here to filter mapping candidates and not the identity rule because if we instead changed the identity rule to $.store.book[?(@.price>10)] and left the repeat rule at $.store.book[*] it would select all messages that have at least one book with a price greater than 10 and then map every book (including those with prices less than 10) to a business entity instance.

After sending the same message a second time we now get this result:

Instead of an additional four business entity instances, we now only have two extra business entity instances (corresponding to the first two rows). Both of which have a price above 10.

See https://goessner.net/articles/JsonPath/ for more information on the supported JSON-Path syntax.

Example getting the values of the properties

It is also possible to show the properties of your message into the grid of the Business Entity. In this next example we show you how to do this.

First we have to create an example interface to get some messages into ConnectPlaza Analyze.

Open the constructor and build the following interface.

Just a normal file pickup, just select a temporary directory like ./temp/filesin or something like that. At the producer site, we place an Analyze wiretap and a Null producer. No special settings there.

For our service we create a Header enricher with the following specifications.

Now save this, create a bundle and deploy this to your test ConnectPlaza Agent.

Now that our interface is running we can copy files in the pickup directory. To create some business entities we need some data in our ConnectPlaza Analyze database. So we test our interface by putting some files in the declared pickup directory. In my test i put 3 files into the pickup directory, so I need to see 3 messages in ConnectPlaza Analyze.

This is the expected result. To check if the header value of MyNewHeader is saved within the message, open one of the messages and check the header values.

Now let's create the Business Entity by selecting the type Business Entity in the Choose type selection box. Press the to create a new Business Entity. Give the Business Entity a name. For instance: testProperties. Press the to add some fields. In our case we want to see the value of the property MyNewHeader. Create the field PropertyValue (this is just a name). Now save the Business Entity. Now select the testProperties Business Entity again in your ConnectPlaza Analyze screen and select the to edit your Business Entity. Click on the rules button and the button to add a Match entry. Select the interface, flow and component like this.

Press to save the entry

Now open the Match entry to enter the rules of the Business Entity. We start with an Identify Rule. In our example we want every message passing our Business Entiry. So we enter an expression which is always true.

The reference must be the name of the property you want to view. The rest speaks for itself I think.

Save the rule set and put some files in the pickup directory. In my example you will get the following screen if you select the created Business Entity.

As you can see, the expected value of HEADERVALUE is displayed as the properties value, which is ok.

Duplicate a Business entity to another Connect Agent

When you have multiple ConnectAgents it can be necessary to duplicate a created business entity to another ConnectAgent. For instance you have created a Business entity on your test environment to check everything is working as it should and now you are ready to release this Business entity to your production environment. To do this you have to follow the next procedure.

Open ConnectPlaza Analyze and select the ConnectAgent where the your Business entity resides.

Open the Business entity with the . At the bottom of the dialog you see the button . Press the button and you can save the file. This will be a .businessentity file. As shown below in the example.

Close the screen by pressing the Cancel button.

Now open your ConnectAgent where this business entity must be imported. Select in ConnectPlaza Analyze your the ConnectAgent where the import must be done.