Documentation fault with entity\sumRelated

[MatLudlam]

Hi, I am looking at the documentation here: https://www.espocrm.com/documentatio...ation/formula/ specifically at the entity\sumRelated item.

Currently the example says:

entity\sumRelated('opportunities', 'amountConverted', 'won')

This should say:

entity\sumRelated('opportunities', 'amountConverted', 'Closed Won')

In looking at the documentation there also seems to be a [not tested] similar error in the definition of record\count. This is confusing because you can use KEY / VALUE pairs or a FILTER.

Once example says

record\count('Opportunity', 'open')

so as there is no KEY / VALUE, I am assuming that the 'open' would be a FILTER applied to the Stage ENUM. There is no value 'open' in the default system within Stage.

You also have a confusing example

record\count('Opportunity', 'accountId=', id, 'stage=', 'Closed Won')

which seems to mix KEY / VALUE pairs with FILTERs. I have not tested this, but can the system really accept both FILTERs and KEY / VALUE pairs in one item. This must lead to confusion.

You use the text

KEY1, VALUE2, [KEY2, VALUE2 ...]

in a few places, I would suggest this should be

KEY1, VALUE1, [KEY2, VALUE2 ...]

As a general points, it would be great if you could

1. Define what a FILTER is (I am guessing a filter is applied to the "Status Filed" that is defined for the entity). Can I use a report wherever a FILTER is valid?
2. Be clear what the default ENTITY_TYPE names are, and their capitals. Is it "Opportunity" or "Opportunities" or "opportunity"
3. Be clear what the default LINK names are. These are not shown on the Entity, e.g. I look at Accounts, there is no filed called "opportunities", so where to I look to confirm what it is? Again capitals and plural are important.
4. Be clear what the ATTRIBUTEs are. You sort of define it at the top under "Attribute" but not really.

The issue here is that when we use script it either works, or (more commonly) nothing happens; there are not error messages. We then have to look at the documentation and guess what is wrong, randomly changing things until it works. Clear documentation would be a great step to improving this. Anything else you could do to improve it would be greatly appreciated, but I appreciate harder than fixing the documentation.

Thanks for all the help with a great product.

[yuri]

> This should say

entity\sumRelated('opportunities', 'amountConverted', 'won') -- is CORRECT.

If something seems ODD, it's because it's how it should be. Legacy and other constrains dictate how it is.

[yuri]

'open' is a internally defined filter name. You don't need them if you are not a developer.

[MatLudlam]

Hi, thanks for the quick response.

I started this thread because I couldn't get the above example to work (on the Accounts table). In the end I used

quoteWonValue=entity\sumRelated('opportunities', 'amountConverted', 'Closed Won') + 10.00;

And it came up with the right answer, 110 in my example.

This all then highlights the 2nd part of my post, can we have clear documentation please? It is very hard to know what to put into what field. The definition of that function says

entity\sumRelated(LINK, FIELD, [FILTER])

but FILTER is never defined. This is even harder when trying to get this to work of the Quotes table.

[yuri]

quoteWonValue=entity\sumRelated('opportunities', 'amountConverted', 'Closed Won') -- WON"T WORK.

Actually, it's stated how you can use FILTER with Report filter. It's clear and people use it.

You can't use KEY => VALUIE pairs here. It's just not supported.

[MatLudlam]

Sorry, I don't understand. I am not a developer, and I want to use the sum\Related function and I just want items that are "Closed Won", what do I do?

Can you define what a FILTER is then?

[yuri]

> which seems to mix KEY / VALUE pairs with FILTERs. I have not tested this, but can the system really accept both FILTERs and KEY / VALUE pairs in one item. This must lead to confusion.

I don't see problem here. I don't understand. We add something that people need to use and we don't need to document it because it must lead to confusion? NO.

[MatLudlam]

Sorry, documentation is always great, the point is that this is not a defined syntax, only an example.

If this is supported then the syntax needs to be defined. Also does it work with any number of KEY / VALUE pairs, or only the one pair as the example?.

[yuri]

Sorry, I don't understand. I am not a developer, and I want to use the sum\Related function and I just want items that are "Closed Won", what do I do?

Can you define what a FILTER is then?

I stated above that these filters are available only for developers and there are just a few of them available by default.

entity\sumRelated('opportunities', 'amountConverted', 'won') -- should work. Unless you have many-to-many relationship, where it can work not properly.

[MatLudlam]

So what FILTERs can I use then? I want to do a sum on the Quotes table, or in the future a table that I build. What FILTERs are available? Hoe about if I want things that are not "won" etc.

All I am after is the definition of what a FILTER is, and how I can work out which ones are available so that I can use them.

[yuri]

For quotes there's only one filter 'approved' that filters records with status equals Approved. You can create filters using Report Filters as it's stated in the documentation. It's the only way to create custom filters available from UI.

[MatLudlam]

Hi, thanks for the clarity, but the 2nd part of my post remains, can someone update the on-line documentation to clearly define these things please.

It is extremely hard to work out what does what. We sort of have some information about what a FILTER is here, but nobody reading the on-line documentation would ever find it. The other items that I highlight are also issues.

I have spent a lot of time looking at these functions over the months, and it always takes longer than it should to get something working, normally because the documentation is too brief.

Thanks in advance.

[yuri]

System LINK names can be found at Administration > Entity Manager > ... > Relationships.

ATTRIBUTE name usually is the same as a system field name. Listed in Entity Manager > ... > Fields.

ENTITY_TYPE list available in Entity Manager.

[MatLudlam]

Can you add that to the on-line documentation and add FILTER please. Can you also expand which column the LINK relates to, so if I look at the Account ENTITY and want to look at the opportunity items, which name do I use "opportunities" or "Opportunity".

Please don't put the answers here, add them to the documentation so that I and everyone else can find them when we need them.

[yuri]

I can't update documentation right now.

[MatLudlam]

Hi, I appreciate that, this is why I have it in the bugs category.

I was thinking that this would be treated like a bug, and resolved at some [not to far off] future release.