REQUEST A DEMO

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.

Demystifying focus_obj2act_entry

 

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

image

 

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.

image

 

 

Conditions

We’ll add a condition: If the user who did the activity (the Logger) is NOT the current owner of the case.

 

image

 

Business Rule Action

The action will notify the case owner.

image

 

Notice that the message includes:

Logger – we’ll use this property again, so we can tell the case owner who performed the action

Activity Namewhat 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:

image

 

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.

Comments

ADD COMMENT

Your email address will not be published.