Demystifying the focus_obj2act_entry relation
I’ve had multiple people inquire lately about the focus_obj2act_entry relation.
It’s definitely a bit of a magic relation, and can be confusing, so I figured it was time to blog about it.
Business rule properties allow you to define a value that is determined by traversing through the schema starting from a particular object.
For example, the Site Name property for a Case has a path of case_reporter2site:name. So when this rule property gets resolved, the property evaluator knows how to turn that schema path into actual SQL, such as:
select name from table_case, table_site
where
case_reporter2site = table_site.objid
and table_case.objid = {The Objid of the Case in Context}
Pretty straightforward.
focus_obj2act_entry properties
When looking at existing business rule properties, you may notice that some of them start with the relation focus_obj2act_entry.
For example, the Logger property uses focus_obj2act_entry:act_entry2user:login_name
Notice the “focus_obj2act_entry” part of the path. If you look at your schema, you won’t see this relation defined anywhere. This is a special, virtual relation that the property evaluator knows how to handle. It knows how to translate “focus_obj2act_entry” into the actual relation based on the Object Type.
For example, for a Case, it translates focus_obj2act_entry to case_act2act_entry. For a subcase, it translates focus_obj2act_entry to subcase2act_entry. Etc.
But, since there can be many act_entry records for a case, the property evaluator has to know how to figure out which single act_entry record we’re talking about.
Remember that the way a business is executed is by the use of a time_bomb record.
The time_bomb has a number of fields, including
- focus_type – which tells us what kind of object this time bomb is for (case, subcase, change request, etc.)
- focus_lowid – which tells us the objid of the focus object, i.e. the objid of the case.
- time_period – which tells us the objid of the act_entry object associated with the time bomb creation event.
So since we have the act_entry objid, this is how we figure out which one of the many act_entry records for the case that we’re talking about.
SELECT
table_user.LOGIN_NAME
FROM table_case, table_act_entry, table_user
WHERE
table_case.objid = {The Objid of the Case in Context}
AND table_act_entry.objid = {The Objid from table_time_bomb.time_period}
AND table_case.objid = table_act_entry.act_entry2case
AND table_act_entry.act_entry2user = table_user.objid
Notice this where clause: table_act_entry.objid = {The Objid from table_time_bomb.time_period}
That’s where the query gets limited to one act_entry record.
So our Logger property will get resolved to the user who performed this one particular activity, whatever that activity may be.
Usage Example
Lets look at how we could use these focus_obj2act_entry rule properties.
Lets create a Business Rule that notifies the owner of a case if a log is performed by someone else. A pretty useful rule.
Business Rule and Start Events
We’ll create our business rule, and set it to fire on Log Email, Log Notes, Email In, or Case Close actions.
Conditions
We’ll add a condition: If the user who did the activity (the Logger) is NOT the current owner of the case.
Business Rule Action
The action will notify the case owner.
Notice that the message includes:
Logger – we’ll use this property again, so we can tell the case owner who performed the action
Activity Name – what action happened. This property also uses the focus_obj2actentry relation (focus_obj2act_entry:entry_name2gbst_elm:title)
What notes were added. If it’s a Notes Log, the Notes Text property also uses the focus_obj2act_entry relation (focus_obj2act_entry:act_entry2notes_log:description)
So you can see that we’re really taking advantage of properties that use the focus_obj2actentry relation.
Result
When someone else logs a note to this case, the owner will receive a notification message:
Logs
If you really want to see the specifics of what’s happening, take a look at the Rulemanager logs:
DEBUG Dovetail.SDK.Properties.Policies.StandardPropertyTokenExpansionPolicy -
Path "focus_obj2act_entry:act_entry2user:login_name"
expands to SQL command
DEBUG "SELECT T2.objid, T2.LOGIN_NAME FROM table_case T0, table_act_entry T1, table_user T2 WHERE T0.objid = {0} AND T1.objid = {1} AND T0.objid = T1.act_entry2case AND T1.act_entry2user = T2.objid ORDER BY T2.objid DESC"
INFO FChoice.Common.Data.SqlHelper - Executing Reader query with command
Command:
SELECT T2.objid, T2.LOGIN_NAME FROM table_case T0, table_act_entry T1, table_user T2
WHERE T0.objid = @1 AND T1.objid = @2 AND T0.objid = T1.act_entry2case AND T1.act_entry2user = T2.objid
ORDER BY T2.objid DESC
Parameters:
@1 = 268439735 (String)
@2 = 268473231 (String)
INFO FChoice.Common.Data.SqlHelper -
Execute reader query complete.
Query ID: aabb5b76-314a-46ef-933e-b320b683bafa
Duration: 0.0004 seconds
DEBUG Dovetail.SDK.Properties.Policies.StandardPropertyTokenExpansionPolicy -
Property "Logger" using "focus_obj2act_entry:act_entry2user:login_name" expands to "hank"
We can see all the detailed information about how it resolved the Logger property, and what it resolved it to.
Which objects can I use this with?
I mentioned earlier that for a Case, the property evaluator translates focus_obj2act_entry to case_act2act_entry. For a subcase, it translates focus_obj2act_entry to subcase2act_entry.
So which objects can I use this with, and what does it translate focus_obj2act_entry into?
Here’s the answer:
| Object | focus_obj2act_entry translated into… |
| case | act_entry2case |
| subcase | act_entry2subcase |
| bug | act_entry2bug |
| probdesc | act_entry2probdesc |
| demand_dtl | act_entry2demand_dtl |
| site | act_entry2site |
| contact | act_entry2contact |
| contract | act_entry2contract |
| email_log | act_entry2email_log |
| commit_log | act_entry2commit_log |
| task | act_entry2task |
| opportunity | act_entry2opportunity |
| schedule | act_entry2schedule |
| onsite_log | act_entry2onsite_log |
| part_trans | act_entry2part_trans |
| site_part | act_entry2site_part |
| workaround | act_entry2workaround |
Are there any other uses for this?
The focus_obj2act_entry relation is also useful when you have one property that needs to work for multiple Object Types.
When creating business rules, you can use an Object Type of “Case-Subcase”, which means that this one rule will apply to Cases and Subcases.
So in these scenarios, you should use rule properties that can be resolved for both cases and subcases, such as those that start with focus_obj2act_entry.
Kinda hokey, I know.
This is not something that I recommend.
Can I use these for Task Manager variables?
Dovetail Task Manager also uses rule properties. For example, when Task Manager creates a subcase, you can have the subcase title be the same as the case title by using the rule property [Title].
When Task Manager resolves these properties, there is not an act_entry that is in context, so focus_obj2act_entry doesn’t make sense here.
So, can I use these for Task Manager variables? No.
Can I use these for Canned Response variables?
Canned Responses in Dovetail Agent also uses rule properties. For example, I may have a canned response that uses the [Contact First Name] property.
When these canned response properties are resolved, there is not an act_entry that is in context, so focus_obj2act_entry doesn’t make sense here.
So, can I use these for Canned Response variables? No.
Wrap Up
The focus_obj2act_entry relation is always confusing, since it doesn’t exist in the schema anywhere or as a physical column.
It may seem a bit magical in how it works.
But once you understand it, you start to understand its power, and why it’s so useful.
Hopefully this post shed some light onto this magic relation, and showed some ways you can harness its power.
Rock on.
Dig This?
Sign up to get information like this delivered right to your inbox.
