Configuration¶

The Lime Field add-on to CRM has a predefined set of workflows that can be tweaked in certain ways to make the best solution possible for users of both products.

The configuration needs a CRM endpoint, an API key and a config.json.

Data model requirements¶

The Lime Field data model already have the required attributes predefined. The CRMSystemId attribute in Lime Field holds the reference to the lime object in the CRM solution. Example value: helpdesk:1001

While Lime Field has a fixed data model and CRM has not, there are some required lime types and attributes that the add-on needs to keep track of integrated data.

The concept of option fields in CRM are equivalent to picklists in Lime Field. However, the mapping of the case type picklist is using a lime type called helpdesktype since that is the model being used in the Lime Core database model that the add-on is based on.

All picklist options can be found in the API at: https://field/api/picklists/

Important! Picklists in Lime Field may accept empty keys but option fields in CRM can't. Therefore, a key named "empty" must be added to the list of options in CRM.

Attributes¶

limefieldid¶

string, 64 characters

This attribute MUST exist in each integrated lime type
Holds the ID of the object in Lime Field to avoid duplicates
Is meant to be hidden everywhere and only editable in CRM on the helpdesktype lime type (see note below)
Set the "Field Label" attribute in LISA of this Field to Key to avoid it being copied to new objects.

Example value: workorder:181017-2928-10

inactive¶

boolean, yes/no

true/yes in CRM maps to the value Inactive in Field
false/no in CRM maps to the value Active in Field
Is used to mark records in Lime Field as inactive since they are NOT deletable by users using the UI

Dates¶

Properties that are date will be handled as datetimes in the integration with these rules

A date in CRM is the datepart + 00:00:00 in local CRM time zone
The same date in Field is the datepart + 00:00:00 in UTC

For example the date 2020-05-22 is 2020-05-22T00:00:00+00:00 in Lime Field and 2020-05-22T00:00:00+02:00 in Lime CRM.

For all properties of kind datetime, the type datetime with seconds should be used in CRM.

Mapping¶

The add-on has a predefined mapping of most concepts but some of these requires additional configuration to work. The base configuration provided enables all common workflows, but lacks parts that are optional or specific to a customer or industry.

Users and auditability¶

The add-on uses exactly two user accounts when it operates. A "Lime Field" user is needed with full access in CRM, and a "Lime CRM" user is needed in Lime Field. Changes that are sent from CRM to Lime Field will have the created/updated by set to the user "Lime CRM" and changes sent from Lime Field to CRM will be made by the "Lime Field" user in CRM.

This may be confusing sometimes but in most users only use either of the systems, not both. Therefore a personal user account that exist in CRM does not always in Lime Field.

The resource concept in Lime Type defines a person, company or equipment that can be assigned work orders. In many cases, the changes made to cases and work orders in Lime Field are made by users that is a person that works for the company, or is a sub-contractor to the company. Therefore the resource concept is mapped directly to a new lime type that mirrors the resource in Lime Field and is used for auditability in Lime CRM. That means it's the resource relation that will tell the source for an edit to a helpdesk, a history note and so on.

One-way mapping of service units¶

Unlike one-to-one mappings of lime types to concepts in Lime Field, service units are often represented by more than one lime type in the CRM application. Examples are properties, buildings, machines, rentalobject etc.

The preferred way to distinguish these in Lime Field is to also equip them with a specific type attribute in Lime Field, so that the user can see that a particular service unit is a building, a machine and so forth. The many-to-one mapping is also one of the reasons the CRMSystemId property in Lime Field is using the format "limetype:id". While one service unit may have the CRMSystemId set to "property:1001" another one could have the value "building:1001". Not having the prefix of the source lime type would create duplicate CRMSystemId values in Lime Field and would update the wrong lime object in CRM.

The limitation of this mapping is that it's one-way making CRM the master of all service units. That means creation and updates of service units in Lime Field will be visible in Lime Field only. The updates will also be lost when the referenced lime object is updated in Lime CRM.

Important! A user can still create service units in Lime Field but the add-on will ignore them when they aren't created in CRM.

Attribute mappings - one-way, two-way and no-way¶

A fully two-way mapping, where the user can update the value from both systems, is only possible when the lime type is mapped to exactly one concept and exactly one attribute of that concept in Lime Field. For example, if the helpdesk.note attribute is mapped to Case.Note in Lime Field it will be updateable from both systems using this add-on.

One-way mappings are when several attributes are concatenated from CRM into Lime Field. For example, when the attributes helpdesk.firstname_web and helpdesk.lastname_web are concatenated by a space into Case.Note, the add-on will only update the Case.Note attribute in Lime Field when the attribute values changes in Lime CRM and will not update CRM when the Case.Note attribute changes in Lime Field.

No-way mappings are the ones where we obviously cannot map the values at all. These include but are not limited to:

Mapping of a relation into a non-relation attribute
Mapping of a value that does not fit the target attribute (length, format)
Mapping where the option value does not exist in CRM

Mapping of relations¶

To make relation mapping possible, the related type must also have the limefieldid attribute so the add-on can relate the correct record in Lime Field. All relatable data in Lime Field always has the CRMSystemId that will hold the reference to the related record in the format limetype:id.

Mapping directives¶

The mapping section of each workflow (see below) defines the attribute mapping used and will decide if the mapping is one-way or two-way.

Each item in the mapping section are defined using the Lime Field attribute as the key and mapping directive(s) as the value.

Example:

  ...
  "mapping": {
    "limefieldattribute1": { ...mapping directive... },
    "limefieldattribute2": { ...mapping directive... },
    ...
  }
  ...

property mapping¶

Defines a lime type property as the source for the value. Two-way if used alone and not in conjunction with other directives in the same mapping. If mapping an option field an option empty key is required.

Format:

 { "property": "limetype propertyname" }

Example two-way mapping of the title attribute in Lime Field and CRM:

  "title": { "property": "title" }

Example option empty key:

  "priority": {
    "property": "priority",
    "optionemptykey": "empty"
  }

Note: When mapping option field, the options have to match in both systems.

relation mapping¶

Defines a relation mapping.

Format:

  {
    "relation": "limetype propertyname",
    "limetype": "name of related limetype"
  }

Example mapping contract to the company relation:

  "contract": {
    "relation": "company",
    "limetype": "company"
  }

Example mapping primarycontact to the relation attribute named tenant:

  "primarycontact": {
    "relation": "tenant",
    "limetype": "person"
  }

set mapping¶

Used to send a list of relations from CRM to Lime Field.

Format:

  {
    "set":[
      { ...mapping directive 1...},
      { ...mapping directive 2...},
      { ...mapping directive n...}
    ]
  }

Example mapping the owner and tenant relations as a list of contacts:

  "individuals": {
    "set": [
      {
        "relation": "owner",
        "limetype": "person"
      },
      {
        "relation": "tenant",
        "limetype": "person"
      }
    ]
  }

join mapping¶

One-way mapping that can be used to join values from several attributes in CRM into one attribute in Lime Field.

Note: The delimiter will only be added if a directive results in a non-empty string, effectively eliminating series of delimiters such as ", , , " in cases where joined attributes have no content

Format:

{
  "delimiter": "delimiting string",
  "join": [
    { ...mapping directive 1...},
    { ...mapping directive 2...},
    { ...mapping directive n...}
  ]
},

Example joining helpdesk.firstname_web and helpdesk.surname_web into Case.Note:

  "note": {
    "delimiter": " ",
    "join": [
      { "property": "firstname_web" },
      { "property": "surname_web" }
    ]
  }

Example nested joining with different delimiters:

(Result: "firstname_web surname_web, phone_web, email")

  {
    "delimiter": ", ",
    "join": [
      {
        "delimiter": " ",
        "join": [
          { "property": "firstname_web" },
          { "property": "surname_web" }
        ]
      },
      { "property": "phone_web" },
      { "property": "email" }
    ]
  }

coalesce mapping¶

The coalesce mapping is used to select the first non-null relation when there are several possible relation attributes in CRM and the add-on needs to pick one. Useful when there are more than one lime type that defines service units or when there may be several person relations suitable when mapping a primary contact. Please note that this two-way mapping will unset unmatched attributes in Lime CRM.

Format:

  {
    "coalesce":[
      { ...mapping directive 1...},
      { ...mapping directive 2...},
      { ...mapping directive n...}
    ]
  }

Example of picking the building relation as the service unit and fall back to use the property relation if the building is unset:

  "unit": {
    "coalesce": [
      {
        "relation": "building",
        "limetype": "building"
      },
      {
        "relation": "property",
        "limetype": "property"
      }
    ]
  }

Two-way mapping result:

When the building attribute is set in Lime CRM, the link to the building will be set in Lime Field
When the property attribute is set in Lime CRM, and not the building, the link to the property will be set in Lime Field
When the link to the building is set in Lime Field, the building attribute will be set in CRM and the property attribute will be unset
When the link to the property is set in Lime Field, the property attribute will be set in CRM and the building attribute will be unset

Workflows¶

The add-on currently supports the following workflows:

case
contract
files
unit

Most workflows have a mapping section that allows extension to the pre-defined attribute mappings of that workflow.

Case Workflow¶

The flow handles everything related to a case/helpdesk including work orders, log/history, files/documents.

Note: When a person is linked to a helpdesk, it will be created/updated when linked. Persons in CRM not having a linked helpdesk will not be created in Lime Field

Option `setrootunitincrm`¶

Links the root service unit from the hierarchy of the case service unit to a relation field. Used to maintain a link to the root unit in CRM where both a link to the service unit and the root unit is required.

Note: The related lime type given by this option must match the lime type of the service unit on the root level of hierarchies in Lime Field

Format:

  "setrootunitincrm": { ...relation mapping directive... }

Example having the property relation attribute set to the root unit in Lime Field:

  "setrootunitincrm": { "relation": "property", "limetype": "property" }

Option `createhistoryforuq`¶

Toggle that tells the workflow to create a history note containing a text with data from all usage quantities on the case in Lime Field.

Default set to false.

Format:

  "createhistoryforuq": true

Note: Usage quantities with empty descriptions will not be transfered.

The pre-defined mapping used to create history notes having this option turned on:

CRM	Field	Comment
type	-	Hard-coded value "comment" (key)
visible_external	-	Hard-coded boolean value "true"
date	Created
note	Description
helpdesk	Case
workorder	WorkOrder
resource	Resource

Option `usetraits`¶

Toggle that tells the workflow to sync traits from Field to CRM. It will also sync specified trait on work order both from and to CRM.

Default set to false.

Format:

  "usetraits": true

Note: When syncing trait from Field to CRM it will pick the first one in the list.

The pre-defined mapping used to create trait having this option turned on:

Field	CRM	Comment
Title	title
Status	inactive

Pre-defined mapping helpdesk - Case (CRM => Field)¶

CRM	Field	Comment
helpdesktype	Type	String value from helpdesktype.limefieldid

Pre-defined mapping Case - helpdesk (Field => CRM)¶

Field	CRM	Comment
Type	helpdesktype	Uses first helpdesktype limeobject found with limefieldid equal to Case.Type in Field
-	statuscolor	Set to "finished" in CRM when Case is finished or inactive in Field
Started	startdate
Finished	enddate

Pre-defined mapping workorder - WorkOrder (CRM => Field)¶

CRM	Field	Comment
helpdesk	Case	Relation
title	Title
description	Description
inactive	Status
state	State	Option in CRM which MUST have Field work order states: NotStarted, Started, Finished
resource	Resource	Relation to resource
activity	Activity	Option field. Key in CRM maps to picklist value in Field
operatingprocedure	OperatingProcedures	Relation to operating procedure
eventstart	Event
eventend	Event
trait	Trait	Is mapped if option usetraits is true

Pre-defined mapping WorkOrder - workorder (Field => CRM)¶

Field	CRM	Comment
Case	helpdesk	Relation. Helpdesk is created in CRM when first work order is created in Field
Title	title
Description	description
Status	inactive
State	state	Option in CRM which MUST have Field work order states: NotStarted, Started, Finished
Resource	resource	Relation to resource
Activity	activity	Option field. Key in CRM maps to picklist value in Field
Tasks	operatingprocedure	Relation to the last operating procedure link found in Tasks. Note: If the OP have zero tasks, the relation will be unset in CRM.
Event	eventstart
Event	eventend
Trait	trait	Is mapped if option usetraits is true

Pre-defined mapping Log - history (Field => CRM)¶

Field	CRM	Comment
-	type	Hard-coded value "comment" (key)
Date	date
Message	note
Log	helpdesk	Case.CRMSystemId, if case log
Log	workorder	WorkOrder.CRMSystemId, if work order log
Resource	resource	If the User in Field has linked Resource with CRMSystemId

Pre-defined mapping history - Log (CRM => Field)¶

Note: Log is not updatable in Field. Only new history records will be sent to Field. Updates to history in CRM will not be visible in Field.

CRM	Field	Comment
-	Category	Hard-coded value "Comment"
date	Date
note	Message
helpdesk	Log	Uses helpdesk.limefieldid to target cases/id
workorder	Log	Uses workorder.limefieldid to target workorder/id
coworker	DisplayName	coworker.name, if relation to coworker exists

Pre-defined mapping person - Individual (CRM => Field)¶

Note: Only created/updated in Lime Field when linked to helpdesk

CRM	Field	Comment
firstname	FirstName
lastname	LastName
phone	BusinessPhone
mobilephone	BusinessMobile
email	BusinessEmail
inactive	Status

Pre-defined mapping resource - Resource (CRM => Field)¶

CRM	Field	Comment
name	DisplayName
email	Email
phone	PhoneNumber
inactive	Status

Pre-defined mapping Resource - resource (Field => CRM)¶

Field	CRM	Comment
DisplayName	name
Email	email
PhoneNumber	phone
Status	inactive

Pre-defined mapping OperatingProcedure - operatingprocedure (Field => CRM)¶

Field	CRM	Comment
Title	title
Status	inactive	Will be skipped if property does not exist in crm

Note: Only the title and status is sent to CRM as the hierarchical structure of tasks cannot be represented in CRM. Note: Only last operating procedure (if multiple is linked) is sent from Field to Lime CRM.

Pre-defined mapping UsageQuantity - usagequantity (Field => CRM)¶

Field	CRM	Comment
Title	title
Description	description
RegistrationDate	registrationdate	Date.
Activity	activity	Option field. Key in CRM maps to picklist value in Field.
Code	code
VerificationNumber	verificationnumber
Quantity	quantity
PricePerPiece	priceperpiece
CostPerPiece	costperpiece
Discount	discount
TotalPrice	totalprice	Calculated using PricePerPiece * Quantity * ( 1 - Discount ).
TotalCost	totalcost	Calculated using CostPerPiece * Quantity.
Case	helpdesk	Relation to Case.
WorkOrder	workorder	Relation to WorkOrder.
Resource	resource	Relation to Resource.

Contract Workflow¶

Pre-defined mapping `<limetype>` - Contract (CRM => Field)¶

CRM	Field	Comment
inactive	Status

Pre-defined mapping Contract - `<limetype>` (Field => CRM)¶

Field	CRM	Comment
Status	inactive

Files Workflow¶

File+Case - document+file (Field <=> CRM)¶

Since the file object in CRM is not a regular limeobject this mapping is unique in the way that it maps one File in Lime Field to one document + file in CRM. The files will be transfered when they are attached to a case/helpdesk that already exists as a case/helpdesk in Field/CRM or when the case/helpdesk they are attached to is created as a case/helpdesk in Field/CRM.

Pre-defined mapping File+Case - document (Field => CRM)¶

Field	CRM	Comment
Case	helpdesk	The Case file is attached to
File.Path	limefieldepath	The path/file category in Lime Field
File.ContentHash	limefieldetag	The hash of the file content
-	document	Relation. The related file uploaded to CRM
-	type	Option field. Hard-coded value: other

Pre-defined mapping File - file (Field => CRM)¶

Field	CRM	Comment
File	filename	The Case file is attached to
File.Path	limefieldepath	The path/file category in Lime Field
File.ContentHash	limefieldetag	The hash of the file content
-	document	Relation. The related file uploaded to CRM
-	type	Option field. Hard-coded value: other

Pre-defined mapping document - File (CRM => Field)¶

CRM	Field	Comment
filename	File	The Case file is attached to
limefieldepath	File.Path	The path/file category in Lime Field
limefieldetag	File.ContentHash	The hash of the file content

Unit Workflow¶

Components - replaceable parts of service units¶

While a service unit may not be replaceable as a whole (like a property, a building) it may consist of parts that are. Lime Field call these unit components and they have a strong relation to products. A component may be a dishwasher, a WC stool, an energy meter etc in a building. The common thing about these items are that they are bound to a service unit that aren't easily replaceable while the thing itself is.

The mapping of the unit component is defined at unit.component.mapping in the config file and the name of the lime type is given by the unit.component.limetype property. Because of the multi-lime type nature of service units in CRM the unit property mapping must be defined as a coalesce mapping for unit on the helpdesk lime type. If only some of the service unit types used can "have components" in CRM, the component lime type should only have relation fields to those lime types. The coalesce mapping for component.unit should include all service unit lime types that can have a component and that should be mapped to Lime Field.

The component table requires the default fields limefieldid and inactive (see below) and a mapping of the title attribute in Lime Field. If the lime type has no title field, one must be added and must contain descriptions (preferably unique) that identifies each component so it will be clear to service technicians and other users which component they are updating or replacing.

Table specification¶

Name	Type	Length	Readonly	Options/comment
limefieldid	text	64	true	Set the "Field Label" attribute in LISA of this Field to `Key` to avoid it being copied to new objects.
title	text	255		Required. Customizable name.
inactive	yes/no
type	option			Optional.
description	text	1073741823		Optional.
productnumber	text	255		Optional.
serialnumber	text	255		Optional.
model	text	255		Optional.
warrantyenddate	date			Optional.
installationdate	date			Optional.
removaldate	date			Optional.
endoflife	date			Planned 'end of life'. Optional.
externalsystemid	text	1073741823		Optional.

Note: All optional columns are defined in the unit.component.mapping section in the config file and can be named something else in CRM. This specification shows what a new table would look like when mirroring components as they exist in Lime Field.

Components change request¶

The components change request table is a table that mirrors the components change request concept from Lime Field.

Table specification¶

Name	Type	Length	Belongs to	Readonly	Options/comment
limefieldid	text	64		x	Set the "Field Label" attribute in LISA of this Field to `Key` to avoid it being copied to new objects.
title	text	255			Required. Customizable name.
inactive	yes/no				Required.
type	option				Optional. Key in CRM maps to picklist value in Field.
description	text	1073741823			Optional.
productnumber	text	255			Optional.
serialnumber	text	255			Optional.
model	text	255			Optional.
warrantyenddate	date				Optional.
installationdate	date				Optional.
removaldate	date				Optional.
endoflife	date				Optional. Planned 'end of life'.
state	option				Optional. Must contain `New`, `Approved`, `Implemented`.
changetype	option				Required. Must contain `Installation`, `Removal`, `Update`.
externalsystemid	text				Optional.
unit	relation		unit		Required.
unitcomponent	relation		unitcomponent		Optional.
workorder	relation		workorder		Required.

Meter request¶

The meter request table is a table that mirrors the meter request concept from Lime Field.

Table specification¶

Name	Type	Length	Belongs to	Readonly	Options/comment
limefieldid	text	64		x	Set the "Field Label" attribute in LISA of this Field to `Key` to avoid it being copied to new objects.
title	text	255			Required. Customizable name.
inactive	yes/no				Required.
location	text	255			Optional.
metric	option				Optional. Needs option "empty". Key in CRM maps to settings value in Field. Must contain `Celsius`, `kWh`, `MWh`, `m3`, `kVar`.
metervalue	decimal				Optional.
activitycode	option				Optional. Needs option "empty". Key in CRM maps to picklist value in Field.
measureddate	datetime, with seconds				Optional.
componentchangerequest	relation		componentchangerequest		Required.
meter	relation		meter		Optional.

Pre-defined mapping meter - Meter (CRM => Field)¶

CRM	Field	Comment
title	Title
location	Location
metric	Metric	Option field. Key in CRM maps to setting value in Field

Pre-defined mapping Meter - meter (Field => CRM)¶

Field	CRM	Comment
Title	title
Location	location
Metric	metric	Option field. Key in CRM maps to setting value in Field
Unit	property, building, plant or object	Relation to Unit. Set depending on the coalesce mapping in the configuration.
UnitComponent	appliance	Relation to UnitComponent.

Pre-defined mapping metermeasurement - MeterMeasurement (CRM => Field)¶

CRM	Field	Comment
metervalue	MeterValue
activitycode	ActivityCode	Option field. Key in CRM maps to picklist value in Field
comment	Comment
measureddate	MeasuredDate
meter	Meter	Relation
workorder	WorkOrder	Relation

Pre-defined mapping MeterMeasurement - metermeasurement (Field => CRM)¶

Field	CRM	Comment
MeterValue	metervalue
ActivityCode	activitycode	Option field. Key in CRM maps to picklist value in Field
Comment	comment
MeasuredDate	measureddate
Meter	meter	Relation to Meter
WorkOrder	workorder	Relation to WorkOrder

Configuration¶

Data model requirements¶

Attributes¶

limefieldid¶

inactive¶

Dates¶

Mapping¶

Users and auditability¶

One-way mapping of service units¶

Attribute mappings - one-way, two-way and no-way¶

Mapping of relations¶

Mapping directives¶

property mapping¶

relation mapping¶

set mapping¶

join mapping¶

coalesce mapping¶

Workflows¶

Case Workflow¶

Option setrootunitincrm¶

Option createhistoryforuq¶

Option usetraits¶

Pre-defined mapping helpdesk - Case (CRM => Field)¶

Pre-defined mapping Case - helpdesk (Field => CRM)¶

Pre-defined mapping workorder - WorkOrder (CRM => Field)¶

Pre-defined mapping WorkOrder - workorder (Field => CRM)¶

Pre-defined mapping Log - history (Field => CRM)¶

Pre-defined mapping history - Log (CRM => Field)¶

Pre-defined mapping person - Individual (CRM => Field)¶

Pre-defined mapping resource - Resource (CRM => Field)¶

Pre-defined mapping Resource - resource (Field => CRM)¶

Pre-defined mapping OperatingProcedure - operatingprocedure (Field => CRM)¶

Pre-defined mapping UsageQuantity - usagequantity (Field => CRM)¶

Contract Workflow¶

Pre-defined mapping <limetype> - Contract (CRM => Field)¶

Pre-defined mapping Contract - <limetype> (Field => CRM)¶

Files Workflow¶

File+Case - document+file (Field <=> CRM)¶

Pre-defined mapping File+Case - document (Field => CRM)¶

Pre-defined mapping File - file (Field => CRM)¶

Pre-defined mapping document - File (CRM => Field)¶

Unit Workflow¶

Components - replaceable parts of service units¶

Table specification¶

Components change request¶

Table specification¶

Meter request¶

Table specification¶

Pre-defined mapping meter - Meter (CRM => Field)¶

Pre-defined mapping Meter - meter (Field => CRM)¶

Pre-defined mapping metermeasurement - MeterMeasurement (CRM => Field)¶

Pre-defined mapping MeterMeasurement - metermeasurement (Field => CRM)¶

Option `setrootunitincrm`¶

Option `createhistoryforuq`¶

Option `usetraits`¶

Pre-defined mapping `<limetype>` - Contract (CRM => Field)¶

Pre-defined mapping Contract - `<limetype>` (Field => CRM)¶