CRM model overview for scripting

Understanding the business model of your application is important when scripting. The model contains the business logic and persistence that you will be working with. Understanding the main classes that make up the NexJ CRM class model, and how those classes interact with one another, can help you troubleshoot, customize, and expand the existing model.

NexJ Customer Relationship Management model

The two main classes in the NexJ Customer Relationship Management model are Entity and Act.

The Entity class defines entities, which are people and organizations in NexJ CRM, such as a contacts, companies, households, or funds.

The Act class defines activities. An activity is a record of communication with a client. This includes schedule items, activity plans, tasks, documents, emails, and call records. Activities are also known as interactions.

The vast majority of all key function points interact with one or both of these two main classes.

Class models

Class models or entity relationship diagrams (ERDs) are a very helpful tool in understanding the model APIs.

You can view or generate class models using NexJ Studio.

The NexJ Customer Relationship Management model overview diagram allows you to visualize the relationships between key functional areas of the model. Use the following class diagrams to visualize the relationships between the most important classes in the model.

Entity and entity types class model

An entity represents a person or organization, such as a contact, company, household, or fund.

An entity type represents the different kinds of persons and organizations. For example, contact, company, household, and fund are all entity types.

Entity attributes class model

Entity attributes are used to define information about each entity, such as their email address or telephone number.

Act class model

An activity is a record of communication with a client. This includes schedule items, activity plans, tasks, documents,
emails, and call records. Activities are also known as interactions.

The Act class describes the different types of activities.

The ActTemplate class describes the basic information that can be used to create different types of activities.

Entity and Act classes association model

The key association in the model is between the Entity and Act classes. NexJ CRM tracks information about every activity, including the links between activities and entities, such as which activity belongs to which contact or user.

Opportunity class model

An opportunity represents a potential sale of one or more products to a client.

Lead class model

A lead is a person who may be interested in purchasing a product or service.

Integrated lead management lets you manage the entire life cycle of a business contact from an unknown entity to a client.

ACL security model

Access Control List (ACL) functionality permits and restricts access to objects in NexJ CRM.

For more information on ACL functionality, see the Access Control Lists Technical Discussion on the NexJ Developer Community site.

The following objects can be secured through ACL:

Entities
Contacts, companies, and households

Opportunities
Opportunities associated with contacts, companies, and households

Acts
Activities associated with contacts, companies, and households
The ACL_SECURABLE aspect is applied to all classes that are secured by ACL.

Aggregate functions for calculated attributes

You can define aggregate functions for calculated attributes used in your model. Calculated attributes assist you with improving performance as they derive values from information that has already been persisted, which reduces the size of your data store, and the number of commits that must be made to the data store. You can use aggregate functions to obtain a summary output on a set of values.

Syntax

Aggregate functions use the following syntax in an expression:
functionName(arguments)

Aggregate functions for calculated attributes

You can use the following aggregate functions:

average()
Returns the average of all non-null values from the specified expression.

count()
Returns the number of instances in a group.

minimum()
Returns the minimum value from all non-null values of the specified expression.

maximum()
Returns the maximum value from all non-null values of the specified expression.

sum()
Returns a total value for all of the values in the expression.

unique()
Returns only distinct (different) values in a group.

You can add these functions only for relational databases in Scheme code in the Persistence layer in NexJ Studio.

For example, the following code returns a list of entities having a corresponding address count greater than or equal to 3:

(Address'aggregate
   '(entity (: _count (count (@))))
   ()
   '((@ entity))
   '(>= (count (@)) 3)
   '(((@ entity) . #t))
   ()
   ()
)

Primitive functions for timestamp and date attributes

You can use primitive functions to extract integer component values from timestamps and dates.

Primitive function for timestamp and date attributes in a non-persistent expression

NexJ CRM supports the following primitive function for timestamp and date attributes in a non-persistent expression.

date-part(part timestamp timezoneOffset locale calendar)

where:
date-part
This function returns the integer value for a given date component from a timestamp using the ISO-8601 date and time standard.

part
This date component can be a string or a symbol. For example, the attribute value can be one of the following:

• year, month, week, day, hour, minute, second
• 'year, 'month, 'week, 'day, 'hour, 'minute, or 'second

timestamp

The attribute value is a Java timestamp type or a long data type from which the date part is extracted.

timezoneOffset
The attribute value can be one of the following:

• An optional constant signed integer that specifies the amount of time in minutes added to Coordinated Universal Time (UTC) to get the local time for the specified timestamp
• A string, symbol, or java.util.TimeZone argument that specifies the timezone that you want to view your timestamp in, which can be standard time or daylight saving time (DST)
  The default value is your machine context time zone. You can specify a null value.

locale

The attribute value can be an optional Java locale object, JavaScript locale, string, or symbol that represents a specific geographical, political, or cultural region. For example, en-CA string represents the English (Canada) region.

The default value is your machine context locale. You can specify a null value.

calendar

The attribute value can be one of the following:

• An optional string, symbol, or java.util.calendar class, that represents a type of calendar class
• A Java object with the calendar type. For example, you can use the string Gregorian to represent the java.util.GregorianCalendar class.

• The java.util.GregorianCalendar Scheme calendar class or your pre-instantiated calendar object
  The default value is Gregorian. You can specify a null value.

  

  Info

  If you pass in a calendar object that you created yourself and you do not specify a locale, then the expression uses the calendar object that you passed in. Otherwise, it creates a calendar based on the same object type that you passed in with your specified locale.

For example, the following code returns 23.

(date-part hour #m2018-01-01T00:00:00 -60)

where the timestamp represents Tuesday, 1 January 1980 at midnight (which is 24 hours) and the local time zone is 60 minutes behind UTC.

The following code returns 20 or 19 depending on DST, where the America/New_York timezone has a UTC offset of -5:00 for standard time and -4:00 with DST.
(date-part hour #m2018-01-01T00:00:00 "America/New_York")

Primitive function for timestamp and date attributes in a persistent expression

You can use the following primitive function for timestamp and date attributes in persistent expressions.
date-part(part timestamp timezoneOffset)

where:
date-part
The function returns the integer value for a given date component from a timestamp using the ISO-8601 date and time standard.
part
This date component can be a string or symbol. For example, it can be one of the following:

• year, month, day, hour, minute, second
• 'year, 'month, 'day, 'hour, 'minute, 'second

timestamp
The attribute value is a Java timestamp type or a long type from which the date part is extracted

timezoneOffset
The attribute value can be one of the following:

• An optional constant signed integer that specifies the amount of time in minutes added to Coordinated Universal Time (UTC) to get the local time for the specified timestamp

• A string, symbol, or java.util.TimeZone argument that specifies a time zone that will be translated into a constant offset. The default value is your machine context time zone. You can specify a null value.

  

  Info

  This information is for developers with an advanced knowledge of time zones.

  The use of these types in this argument is discouraged; instead persistent date-part expressions should only use a 0 minute offset/UTC, as most timestamps stored in a database will be stored in UTC anyways.

  For example, "EST" and "America/New_York" will be translated into 5 hour offsets from UTC, while "EDT" will be translated into a 4 hour offset.

Info

You cannot edit a timestamp using this function.

The following example applies to a read-only operation and returns all the statistic instances with an hour attribute corresponding to the hour part of their timestamp, and with a time zone offset of 10 minutes:
(SysStat'read '((: hour (date-part 'hour (@ timestamp) 10))) ()()()()())

The following example returns all of the statistic instances with timestamps with the hour part equal to 1 (given a 10 minute time zone offset):

(SysStat'read () `(= (date-part 'hour (@ timestamp) 10) 1)()()()())

For an aggregate query, the following example returns the number of statistic instances for each hour as well as the hour part of the timestamp:

(SysStat'aggregate
   '((: count (count (@))) (: hour (date-part 'hour (@ timestamp) 10)))
   '()
   '((date-part 'hour (@ timestamp) 10))
   () () () ()
)

CRUD life cycle of an object

A class describes a set of objects that share common characteristics and behaviors. Attributes define the characteristics of a class and events model its behaviors. An instance of a class is typically created, read, updated or deleted when a user performs an action in NexJ CRM, or through a SOA or RESTful API call.

When an instance of a class is created and initialized, the create event is invoked by the framework. The create event is then added to a unit of work. A unit of work is a logical grouping of one or more operations, such as other create, update, and delete events, into a single transaction. When the unit of work is committed, the update cycle is initiated.

In the update cycle, create, update, and delete events occur and call other create, update, and delete events. The events execute sequentially until no new events are generated, and then the commit events occur. The commit events execute business logic and persist data to the database.

The commit event is invoked only once per unit of work. If an instance is updated after the commit occurs, then the update is invoked again and the commit is not invoked.

A purge event can be called on a class instance rather than a delete. A purge deletes the instance and ignores auditing and synchronization operations. Therefore, a purge should only be performed when auditing and synchronization operations are not required to execute. Cascade deletions still occur with the exception of custom cascades defined in the delete event of a class.