CRM Integration Plug-in

ignoredmoodusDéveloppement de logiciels

21 févr. 2014 (il y a 3 années et 5 mois)

169 vue(s)


WW
W.GO2GROUP.COM



C
RM Integration Plug
-
in

Software Architecture and Design








Document Revision

2.
2

Issue Date:

April 26
, 2008

Authors
:

Doug Bass







I GNOREDMOODUS_960A18
A2
-
5A6E
-
4FFE
-
A83B
-
1669EF6DED99.DOC

Copyr i ght


2007, Go2Gr oup, I nc. Al l Ri ght s Reser ved.

i

*** PROPRI ETARY AND CONFI DENTI AL ***

TABLE OF CONTENTS


1

Overview

................................
................................
................................
................................
..

1

1.1

R
EVISION
H
ISTORY

................................
................................
................................
.........................

1

1.2

I
NTRODUCTION

................................
................................
................................
................................

1

1.2.1

Audience

................................
................................
................................
................................
.

1

1.2.2

Scope
................................
................................
................................
................................
.......

1

1.2.3

Description

................................
................................
................................
.............................

1

1.3

R
EFERENCED
D
OCUMENTATION

................................
................................
................................
......

3

2

CRMIP Design Goals

................................
................................
................................
...............

4

2.1

S
ECURITY

................................
................................
................................
................................
........

4

2.2

P
ERFORMANCE

................................
................................
................................
................................

4

2.3

C
ONFIGURABILITY

................................
................................
................................
..........................

5

2.3.1

Configuration of the plugin

................................
................................
................................
....

7

2.4

E
XPANDABILITY

................................
................................
................................
..............................

8

2.5

P
LEASING
U
SER
I
NTERFACE

................................
................................
................................
............

9

3

System Architecture

................................
................................
................................
...............

10

4

Data Model

................................
................................
................................
.............................

11

5

Detailed Design

................................
................................
................................
......................

12

6

Installation, Support, and FAQ

................................
................................
..............................

14

6.1

I
NSTALLATION

................................
................................
................................
................................
14

6.2

C
ASE UPDATES

................................
................................
................................
...............................
14

6.3

I
SSUE
U
PDATES

................................
................................
................................
..............................
15

6.4

S
UPPORT

................................
................................
................................
................................
.........
16

6.5

FAQ

................................
................................
................................
................................
...............
17





Copyr i ght


2007 Go2Gr oup, I nc. A
l l Ri ght s Reser ved.


1

of
17

*** PROPRI ETARY AND CONFI DENTI AL ***

1

Overview

1.1

Revision History

Date

Revision

Summary of Changes

May 4, 2007

2.0

Rough Draft.

June 14, 2007

2.
11


Add 2.11 release features
.


1.2

Introduction

1.2.1

Audience

This document is intended to be reviewed by
any one technical in background with an
interest in the inner working of the CRM Integration Plug
-
in (CRMIP).

1.2.2

Scope

This docume
nt presents a design baseline for the CRMIP with a discussion of the
interfaces utilized, and possibilities for extension to other CRM systems. It also discusses
the important topic of security, and also the configuration options of the plug
-
in. The
instal
lation and user instructions for the plug
-
in are described in a separate document.

1.2.3

Description


The CRMIP was originally intended as a solution to a specific customers’ need


integrate jira issue management with an external CRM system (SalesForce). After
some
research it was discovered as a increasing need


integration of external systems with
Jira, eg, CRM, Test, Requirements Management, ERP, and others. Since Atlassian (the
makers of Jira and Confluence) provide a SOAP
1

interface as does SalesForce
2
, th
is
integration seemed possible, and a prototype (version 1.0 of the plug
-
in) proved the
concept, and in fact, elicited the large amount of interest from other users of Jira and
SalesForce.

Subsequent to the first release of the plug
-
in (called the SalesFor
ce plug
-
in) another
customer approached Go2Group for the development of a similar plug
-
in for integration
with a relational database. From that development effort, the CRMIP was born, provided
a mechanism to interface Jira to multiple CRM
-
like systems thro
ugh a pre
-
defined
interface (Dataprovider) and use of a factory pattern to instantiate the proper
implementation of the DataProvider interface.




1

http://www.w3.org/TR/soap/

and
h
ttp://confluence.atlassian.com/display/JIRA/JIRA+RPC+Services

2

http://www.salesforce.com/us/developer/docs/api/index.htm


Copyr i ght


2007 Go2Gr oup, I nc. A
l l Ri ght s Reser ved.


2

of
17

*** PROPRI ETARY AND CONFI DENTI AL ***

The CRMPIP is
the first bi
-
directional

integration of Jira
and SalesForce,
ie, when a user
creates an issue in

Jira, the
associated
SalesForce
information

is
pulled
from

the
SalesForce server
and populated in
the issue.





Also, when the issue is created, updated, resolved, or closed (or any other steps in its
workflow), the issue is pushed to update a case in t
he SalesForce UI (and database).




Figure
2

-

Jira Issue as a Case in SalesForce



Figure
1

-

SalesForce Data In Jira Issue


Copyr i ght


2007 Go2Gr oup, I nc. A
l l Ri ght s Reser ved.


3

of
17

*** PROPRI ETARY AND CONFI DENTI AL ***

Another view into the information in Jira is a window in SalesForce which displays the
issues for a specific Account which can be filtered for th
e logged in user (like a to
-
do
list).


Figure
3

-

Issue List in SalesForce


Finally, as the plug
-
in distributes and provides remote access to sensitive corporate and
personal information security was a paramount concern


all comm
unication and access
is verified for authentication

and authorization, all data transfer is SSL
encrypted
, and all
passwords are stored and communicated in encrypted form
.



1.3

Referenced Documentation

CRMIP Installation Guide.



Copyr i ght


2007 Go2Gr oup, I nc. A
l l Ri ght s Reser ved.


4

of
17

*** PROPRI ETARY AND CONFI DENTI AL ***

2

CRMIP Design Goals

Some of the

design goals of the CRMIP include secure transfer of information, adequate
performance, configurability,
expandability,
and a pleasing user interface.


2.1

Security

The
transfer of proprietary information across any wide area network, especially across the
In
ternet is a risky proposition. All communication protocols and authentication mechanism are
susceptible to crackers, hackers, sniffers, and spoofers. The approach taken to secure the
information transferred by CRMIP between Jira and an external system incl
ude:


1.

Implementation of all security concerns a
s

requested by salesforce
3
.

2.

Encryption, ie, communication is only allowed via Secure Socket layer (SSL)
communication.

3.

All user access is between authorized users via the internal systems login mechanism, ie,
userids and passwords
(or other secure mechanism such as session id)
are passed within
the encrypted channel.

4.

Spoofing attempts are defeated by ensuring the source of the information request is as
expected, eg, remote connection to and from sales force are

only made via an authorized
sales force servers through introspection of sessions headers originating address.

5.

Ajax security concerns have been addresses using the recommended mechanism, eg,
XML
4
.

6.

Passwords are stored and communicated using a 128
-
bit RSA
enlgorithm.


2.2

Performance

The performance tuning of any web application is crucial to its acceptance by users, and CRMIP
is no exception. Performance is addressed in a number of areas:


1.

Data requests to sales force (or other CRM systems) are throttled by th
e number of
connections to these external systems. Currently only one connection is left open to sales
force and all queries and updates are synchronized through this one connection. IN the
future a connection pool may be implemented with a limited size (f
ive is expected).

2.

Query results are cached in memory so identical query are not repeated until the item in
the cache expires (a configurable time limit).

3.

Queries for information from the external system may be limited by two settings in the
properties file
:




3

http://www.salesforce.com/developer/tech
-
notes.jsp?tn=TN
-
18

4

http://www.go2group.com/blog/2007/04/jirasalesforcecom
-
plugin
-
defends.
html


Copyr i ght


2007 Go2Gr oup, I nc. A
l l Ri ght s Reser ved.


5

of
17

*** PROPRI ETARY AND CONFI DENTI AL ***

a.

The number of rows returned from the query, and

b.

An addition to the where clause of the query, eg, account.type=’Active
Customer’ could be specified.

4.

The D
-
HTML screens (actually programmed in the velocity template language) can pre
-
populate l
ists of acco
unts, leads, etc fr
om

a query all of the external crm system. This
method is of course not possible for a user with thousands of accounts so an
a
jax
interface is developed so that the user types the first character of the item in interest (eg
M for all acc
ounts starting with M)
, and only a query for accounts starting with M will be
searched.



Figure
4

-

AJAX Query

2.3

Configurability

Numerous configuration options are available for the plug
-
in


they are described in the below
table.


Table
1

-

Configurable Parameters

Section

Name

Description

Values

Authentication

user

Your salesforce user name



password

Your
encrypted
salesforce password



e
ncrypted
-
password

A value of true will require the password in
the
properties file to be encrypted. False
(never recommended) the user can store the
password in clear text.
.

True or false


DbDatasource

The name of the java datasource to access
your CRM database. Not used for the sales
force plugin.


Fields

ClientCustom
Fie
ldName

The name of the field (Clients in the
previous examples) that contains the
account info from salesforce.com.

Clients


RelatedField

The fields related to the client field, ie, they
are populated when a client is chosen in a
select list.

Contacts,
Opportu
nities,Solutions


ContactField

The contact field


this is needed to save
cases for the contact

Contacts


CaseField

The multi
-
select field created to store the
sales force case
number
’s

Cases


AssignmentRule

The sql used to define the assignment
of
cases. If this rule fails the sales force
specified default rule will be used



Copyr i ght


2007 Go2Gr oup, I nc. A
l l Ri ght s Reser ved.


6

of
17

*** PROPRI ETARY AND CONFI DENTI AL ***


url

The
url to be displayed for each record type
on the Jira view issue screen

Account=https://n
a3.salesforce.com


DataHandler

Class

The
java class to be used for CRM
comm
unication. This should never be
changed unless instructed by Go2Group
support.

com.atlassian.jira.
plugin.customfield
.crm_integrator.co
ntrol.SfCrmServic
e

Performance

Refresh
C
acheIn
Minutes

How often the cache should be refreshed
when quering sales force dat
a

30


WhereClause

Used to limit the data being returned to the
plug in from sales force. Multiple data items
may be specified, eg, accounts and contacts.

account=name
like
't%',contact
s=BillingSta
te=’GA’


PreLoadLists

Used to
load lists from salesforce o
n startup
(eg Accounts, products, etc). A value of true
will preload the list. The default value of
false will not preload the list, and the user
must type the first character in a search box
to diaply values.

true or
false


QuerySize

Maximum number of ob
jects to returned
from a query

250

View

ShortCustom
erSize

Used to trim the amount of
customer info displayed in
the Issue Navigator view.

99


Records

Defines the sales force data
items that can be queried by
the plugin. DO NOT MODIFY.



Account

The fiel
ds to be queried from
sales force for the account
data type. DO NOT MODIFY.


Remote
Updates

onCreate

The list of Jira fields
5

to be
stored in a Salesforce in the
event of a new Jira issue.

Salesforce
-
field=Jira
-
field, etc


onUpdate

The list of Jira field
s to be
stored in a Salesforce case
in the event of an updated
Jira issue.

Salesforce
-
field=Jira
-
field, etc


enable
-
create

True=create a salesforce case
when a Jira issue is created.
False=don’t create a new
salesforce case when a Jira
issue is created.



l
icense

The license provided via
email from Go2Group Sales.











5

The names of the possible Jira fields are contained in Table 2.


Copyr i ght


2007 Go2Gr oup, I nc. A
l l Ri ght s Reser ved.


7

of
17

*** PROPRI ETARY AND CONFI DENTI AL ***

Table
2

-

Jira Field Names


Jira Field Name

Data Type

Description

affected
-
v
ersion


SDL
6


assignee

char

Jira user name

assignee
-
email

char

Jira user email addr
ess

component

CDL
7


created

timestamp


d
escription

Char


d
ue
-
date

Timestamp


e
stimate

Number


f
ix
-
version

SDL


issue
-
type

Int

Zero based (0 to n
-
1)

key

Char

Issue id, eg, PRJ
-
2234

original
-
estimate

Number


parent
-
id

Char

Issue id of the parent is
sue

priority

Int

One based (1 to n)

project

Char


reporter

Char

Jira user name

reporter
-
email

Char

Jira user email address

resolution

Character

Resolution or Unresolved

decurity
-
level

Char


dtatus

Int

Zero based (0 to n
-
1)

dummary

Char


time
-
spent

Number


updated

Timestamp


votes

Number

Number of votes for the issue

Jira custom field name

Any

Any jira custom field name, eg, Case



An example of using the fields in the previous table to specify the fields to be updated in a
salesforce case when
a Jira issue is updated is below. Note the format is salesforce
-
field=Jira
-
field. The salesforce
-
field names are defined in the salesforce api document. Also, salesforce
custom field may also be specified (eg custom
-
field
-
name__c).


onUpdate=Type=issue
-
typ
e,Subject=summary,Status=status,Origin=key,Priority=priority,Description=Cus
tom Date


2.3.1

Configuration of the plugin

Initial configuration of the plugin is performed u
s
ing the installer. This creat
s

a
sa
l
esforce.properties file in the {JIRA
-
INSTALL}/Atlassian
-
jira/WEB
-
INF/classes
folder. This file contains ALL possible configuration options for the plugin.





6

SDL is a semi
-
colon delimited list, eg, “version1; version 2”

7

CDL is a comma delimited list


Copyr i ght


2007 Go2Gr oup, I nc. A
l l Ri ght s Reser ved.


8

of
17

*** PROPRI ETARY AND CONFI DENTI AL ***

Subsequently, a Jira administrator may use the menu option with the Jira Admin Gui (as
shown below) to modify the more common configurable parameters. Once

these
parameters have been saved from the Gui, these options are

stored in the Jira database.
T
his means that the Gui options override the parameters stored in the
salesforce.properties configuration file, ie, on Jira startup the parameters are read
first

from the properties file, and then some of the parameters may be replaced if they are
stored in the database. The configuration Gui looks like this:



2.4

Expandability

The initial implementation of the plug
-
in was developed for solely an interface to salesf
orce.com
but once it was realized this same plug
-
in could be used as a general interface to external CR
M

systems, the code was re
-
architected to allow expansion. A java interface has been defined (called
DataProvider) whose goal is to provide an extension
mechanism, ie, the interface is defined to
support data transfer to a new CRM system, the name of the new class is entered in the properties
file, and voila, a new CRM system has been integrated with Jira.


The following interface makes several assumptions
:

1.

Information from the CRM system is structured as records, with each record containing

a
unique id (a primary key).

2.

The entities in the CRM system (eg Accounts, Contacts, Products, etc) are structured as
parent entities, and child entities. For example, s
alesforce uses Account as a parent entity,
and Contact as child entities of Account (ie, Contacts are listed for or within Accounts).

3.

The entities to be queried, and the fields to be queried for each entity type are controlled
by settings in the properties

file, eg:


Copyr i ght


2007 Go2Gr oup, I nc. A
l l Ri ght s Reser ved.


9

of
17

*** PROPRI ETARY AND CONFI DENTI AL ***


account=id(primary),name, phone, AccountNumber, BillingStreet

contact=id(primary),AccountId(Parent
-
account),phone


4.

Each method return a list of found records, and each record is represented as a map where
the key is the field name (eg “BillingS
treet”), and the value could be “10 Main Street”.



The methods that must be defined for a new integration are

defined the DataProvider java class.




2.5

Pleasing User Interface

Currently the AJAX style interface is used to provide a useful and comfortable an
d efficient
interface. In the future, a more compact interface is anticipated, where more of the width of the
page is utilized, instead of the length (the standard jira approach to displaying information).




Copyr i ght


2007 Go2Gr oup, I nc. A
l l Ri ght s Reser ved.


10

of
17

*** PROPRI ETARY AND CONFI DENTI AL ***

3

System Architecture


An overview of the system a
rchitecture is illustrated below, mostly composed of the
standard products from SalesForce and Atlassian (Jira), with the addition of the new
CRMIP plug
-
in which implements custom fields, servlets, and DataProvider

module to
access the external CRM system
(eg SalesForce).


Jira Issue
Database
SalesForce
Cases
Jira Users
SalesForce Users
Jira Application Server
CRMIP Plugin
-
in
SalesForce Application Server
CRMIP
Properties
File
SalesForce Soap API

Figure
5

-

CRMIP System Architecture


Copyr i ght


2007 Go2Gr oup, I nc. A
l l Ri ght s Reser ved.


11

of
17

*** PROPRI ETARY AND CONFI DENTI AL ***

4

Data Model


The data model for the plugin is very simple


in SalesForce Cases are stored which
replicate the issue information in a Jira issue, e
g, Title, Description, Jira Issue ID (PRJ
-
332), Status (Open, resolved, Closed, etc), Type (Bug, Feature, etc).


Issues within jira store the primary keys (ie Ids) of the sales force references, eg,
Accounts or Contacts are stored in the Jira Issue in a cu
stom field. The custom field
contains the unique 15 character SalesForce id for the object. As an issue is displayed, the
CRMIP plug
-
in queries the SalesForce server to translate the id into several user readable
fields, eg, Name, Address, Phone, etc. As d
iscussed in the previous section, this
information is cached so as to minimize the queries to the external CRM system.


The actual value for the custom field is stored in the CustomFieldValue table (as defined
in the entitymodel.xml file


a standard part
of the Jira distribution).


Copyr i ght


2007 Go2Gr oup, I nc. A
l l Ri ght s Reser ved.


12

of
17

*** PROPRI ETARY AND CONFI DENTI AL ***

5

Detailed

Design


The inner workings of the CRMIP plug
-
in utilize the standard structure of a Jira plug
-
in,
ie, view screens implemented in velocity (stored in the templates directory), a properties
file, an atlassian
-
plugin.xml f
ile which describes the different ‘pieces’ of the plugin, and
the java code (divided in util, servlet, view, and control packages).



Copyr i ght


2007 Go2Gr oup, I nc. A
l l Ri ght s Reser ved.


13

of
17

*** PROPRI ETARY AND CONFI DENTI AL ***


Figure
6

-

CRMIP Plugin Source Modules


Copyr i ght


2007 Go2Gr oup, I nc. A
l l Ri ght s Reser ved.


14

of
17

*** PROPRI ETARY AND CONFI DENTI AL ***

6

Installation,
Support
,
and FAQ


6.1

Installation

For complete

installation instructions please review the

Installation Guide
.

The installation of the plug
-
in is identical to other Jira plugins, ie, copy the jar file to the WEB
-
INF/lib directory, copy the properties files to the WEB
-
INF/classes directory (or anywhere

in the
java classpath), restart the Jira server, and create the desired custom fields (eg Account, Contacts,
Opportunities, etc). Please note that for the case update facility to function properly the
RemoteTicket java class must also be installed as a ji
ra listener. More setup information for case
update follows in the next section.


6.2

Case updates


For the plug
-
in to automatically update the cases in SalesForce (or other external CRM systems),
several components must be active:


1.

Add and update permissions
must be enabled for cases in the external CRM system.

2.

The custom field to store the case ids must be created in Jira (a multi
-
select field as one
case each created for each contact referenced in the issue). This custom field must also be
listed in the prop
erties file, eg, CaseField=Cases.

3.

The Contact field must be referenced in the properties file (eg ContactField=Contacts).

4.

The jira issue must have both an Account (sometimes also called a Client) value selected,
and also it must have a Contact value select
ed.

5.

The RemoteTicket java class must be installed as a Jira listener.


All of these conditions MUST be true for the case update facility to work, otherwise, case

updates are not attempted by the plug
-
in.


In a particular installation the most efficient app
roach to disabling case updates is not to
install the RemoteTicket class as a Jira listener.


Synchronization of case updates


The replication of jira issues to SalesForce is one of Master
-
Slave replication, ie, any updates
to the jira fields (eg Summary,
Description, Status, etc) are written to the external CRM
system. If previous edits of these fields were performed by the SalesForce user (or external

Copyr i ght


2007 Go2Gr oup, I nc. A
l l Ri ght s Reser ved.


15

of
17

*** PROPRI ETARY AND CONFI DENTI AL ***

CRM user), these edits will be overwritten. It is suggested that Jira is given full control of all
case i
nformation by making these fields read
-
only to the SalesForce user.


6.3

Issue Updates

Jira issues can be created or updated from the Salesforce case screen by pressing the
‘Create/Update Jira Issues’ button as seen below:




When the salesforce user presses
the button, information is sent to a servlet installed in
Jira that will create a new Jira issue, or update an existing Jira issue. If the Case origin
field has a valid Jira Issue Id (as in the previous example


SF
-
25) the Jira issue will be
updated, othe
rwise a new Jira issue will be created, and Jira will save the new Jira issue
id in the Case Origin Field. Actually, the specific field that stores the Jira issue id is
defined in the onCreate and onUpdate properties previously discussed.

For the button to

correctly perform its function, a URL is attached to the button. An
example of the buttons’ URL is:


http://{!INCLUDE($SControl.jiraIntegration__Jira_Server)}:{!INCLUDE($SControl.jira
Integration__Jira_Port)}/plugins/servlet/create
-
issue?affected
-
version=1
.01&fix
-
version=1.01&component=GUI&jira_user={!INCLUDE($SControl.jiraIntegration__Jira
_Username)}&pwd={!INCLUDE($SControl.jiraIntegration__Jira_Password)}&project=
{!INCLUDE($SControl.jiraIntegration__Jira_Project)}&{!INCLUDE($SControl.jiraInte
gration__Jira
_Account_Field)}={!Case.AccountId}&issueid={!Case.Origin}&{!INCLU
DE($SControl.jiraIntegration__Jira_Contact_Field)}={!Case.ContactId}&comment={!C
ase.Last_Case_Comment}&{!INCLUDE($SControl.jiraIntegration__Jira_Case_Field)}=
{!Case.Id}&summary={!Case.Subject
}&description.get(Case.Description)&issueType=1
&status=0&priority=1&reporter={!Case.OwnerEmail}&debug&affected
-
version={!Case.jiraIntegration__Affected_Versions__c}



Copyr i ght


2007 Go2Gr oup, I nc. A
l l Ri ght s Reser ved.


16

of
17

*** PROPRI ETARY AND CONFI DENTI AL ***

Notice that some of the tags used are defined in Table 2


the Jira field names, eg,
affec
ted
-
version and component. Other
s

are specific to the button needed to create or
update a Jira issue, eg:

1.

Jira
-
user

2.

Pwd

3.

Comment


There is also a debug parameter which will display in a subsequent html page the
expanded parameters passed to the Jira servlet
.

Another addition to the URL is in support of large text area fields. If there are several of
these the amount of data in one URL string may be too large, ie, it exceeds the maximum
size of a GET URL as defined by the HTTP standards. To handle this limita
tion, a text
area field can be specified in the URL using the format:


Jira
-
field
-
name.get(salesforce
-
field
-
name)

In this way, the field names are passed to the Jira servlet, and the servlet will then query
the salesforce database for the actual field valu
e (which may be much larger than the
maximum size of an Http Get).

Note that several parameters are stored in S
-
Controls. These a
r
e global fields that can be
defined in salesforce to store parameters, eg, the jira port number, server address, etc. An
examp
le is:




The buttons’ URL can also be modified to support more features


this is up to your
salesforce administrator. For example, the URL is configured to store all Jira issues in a
single Jira project. A different option would be the salesforce user w
ould define which
Jira projct the issue will be stored in. How can this be accomplished? A pick list could be
defined in salesforce with the available Jira project names, and a case statement could be
added to the URl to send to Jira the proper project key
.

6.4

Support



Copyr i ght


2007 Go2Gr oup, I nc. A
l l Ri ght s Reser ved.


17

of
17

*** PROPRI ETARY AND CONFI DENTI AL ***

All support of the CRM product is performed via the Go2group Customer Support sites
(
http://www.gotogroup.com:9011

and
http://www.gotogroup.com:9021
) a
nd email
(support.go2group.com). Online support via Web
-
Ex sessions is also available at current
consulting hourly rates.


6.5

FAQ


See the customer support wiki for the latest FAQ.