Sugar 5.5 Web Services

learningsnortSecurity

Nov 3, 2013 (3 years and 9 months ago)

113 views

































SugarCRM, Inc.

10050 N. Wolfe Road

SW2
-
130

Cupertino, CA 95014

T:
408.454.6900

F: 408.873.2872

Sugar 5.5 Web Services

Design Overview Document

Sugar 5.5 Web

Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

i



Developer Note: Sugar 5.5 Web Services Overview

Author: Samir Gandhi

Date: 0
1/28/2009

Sugar Version: 5.5

Sugar Edition: CE/Professional/Enterprise


This document is subject to change without notice.


License


This work is licensed under the Creative Commons Attribution
-
Noncommercial
-
No Derivative
Works 3.0 License (“License”). To
view a copy of this license, visit
http://www.creativecommons.org/licenses/by
-
nc
-
nd/3.0/
or send a letter to Creative Commons,
171 Second Street, Suite 300, San Francisco, California, 94105, USA.


Disclaimer

Your Warranty, Limitations of liability and Inde
mnity are expressly stated in the License. Please
refer to the License for the specific language governing these rights and limitations


Trademarks

All SugarCRM logos in this document are registered trademarks of SugarCRM Inc. See the
SugarCRM trademark po
licies at http://www.sugarcrm.com/crm/open
-
source
/trademark
-
information.html for
more information on how SugarCRM trademarks can be used
.


















Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

ii

Table of Contents


Document Overview

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

1

API Overview

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

1

New API Set

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

1

login()

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

2

logout()

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

3

seamless_login()

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

3

get_user_id()

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

4

get_entry()

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

4

get_entries()

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

5

get_entry_list()

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

7

get_relationship()

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

8

get_note_attachment()

................................
................................
................................
.......
10

get_document_revision()

................................
................................
................................
....
10

set_entry()

................................
................................
................................
..........................
11

set_entries()

................................
................................
................................
.......................
12

set_relationship()

................................
................................
................................
...............
13

set_relationships()

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

set_note_attachment()

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

set_document_revision()

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

search_by_module()

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

get_server_info()

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

get_module_fields()

................................
................................
................................
...........
18

Interfaces

................................
................................
................................
................................
.
18

SOAP Overview

................................
................................
................................
....................
18

REST Overview

................................
................................
................................
.....................
19

Ve
rsioning

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

Error! Bookmark not defined.


Sugar 5.5 Web

Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

1

Document Overview


This document outlines the updates we are building to our web services framework that will be
released i
n

the upcoming 5.5
version of Sugar CE, Professional and Enterprise.


This
document
wil
l be updated as we approach the release in the summer time where its contents will be
moved to the Sugar 5.5 Developer Guide. We are releasing this document early to explain the
approaches we took
, what to look forward to

and solicit feedback from the com
munity to help
further updates/additions we might include
in the future
.


Besides updating the existing SOAP interface with a revamped li
st of available calls,
we are
introducing

major updates
to the framework such as Versioning and Extensibility,
and the
addition of a
new REST interface
.

API Overview


In version 1 of our web services API we had a plethora of calls allowing you to get at almost any
piece of data in the system. One downside of the amount of calls we had was that
accomplishing certain tasks
via the API can be burdensome having to make three or four calls
to finish your task. Traversing and retrieving the details of related items is one such example.


In version 2 we have rewritten all of the API calls. Based on what we
learned from
version
1 we
have been able to
reduce
the number of calls down to 20

by allowing
you to pass extra
parameters in
to certain calls
and eliminate the number of round trips to the server.


New API Set


Those familiar with version 1 of our API will find it easy to lea
rn version 2. This section will
cover all the calls in detail including example input/output.


Table 1:

List of New API Calls

Call

Description

login()

Logs the user into the Sugar application and
create a session

logout()

Logs out the user and ends the
current session

seamless_login()

Used for Sugar Offline Client or to accomplish
single sign on

get_user_id()

Returns the user_id of the user who is logged
into the current se
s
sion

g
et_entry()

Retrieves a single record with details based on
the ID

g
et_e
ntries()

Retrieves multiple records based on IDs. This
Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

2

API is not a
p
plicable to the Reports module.

g
et_entry_list()

Retrieves a list of records for a given module

g
et_relationship
()

Retrieves a collection of module records that
are related to a target r
ecord and optionally
return relationship data for the related beans.

get_note_attachment()

Retrieves an attachment from a note

get_document_revision()

Allows an authenticated user with the
appropriate permission to download a
document.

s
et_entry()

Creat
es or updates a single module record

s
et_entries()

Creates or updates a list of module records

set_relationship()

Sets a single relationship between two records
where they are related by module name and ID.

s
et_relationships()

Sets multiple relationship
s between two records
where the
y

are related by module name and ID

set_note_attachment()

Adds or replaces an attachment to a note

set_document_revision()

Sets a new revision to the document

s
earch_by_module()

Returns the ID, module_name, and fields for
the
specified modules as specified in the search
string.

get_server_info()

Obtains server information such as version and
GMT time

get_module_fields()

Retrieves the vardef information on fields of the
specified
module



login()


Logs the user into the S
ugar application and creates a session


Syntax


login($user_auth, $application)


Example
:


To log in a user:


login

array(

'user_auth' => array(

Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

3

'user_name' => 'admin',

'password' => '21232f297a57a5a743894a0e4a801fc3',

'version' => '2'

),

'application_name
' => 'SoapTest'

)

);


Table 2:

login() arguments

Name

Type

Description

$user_auth

(required)

Array

Set login properties such as
username, password and API
version

$application_name

(
optional
)

String

Name of your application that is
connecting to the web
service


logout()


Logs out the user and ends the current session


Syntax


logout($session)


Example
:


To log out a user:


logout(
'4d8d6c12a0c519a6eff6171762ac252c');


seamless_login()


Used for Sugar Offline Client or to accomplish single sign on.


Synta
x


seamless_login($session)


Example
:


To get vardefs from the Bugs module:


seamless_login
array('session' => $sessionid)


Table
4
:

seamless_login() arguments

Name

Type

Description

Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

4

$user_auth

(required)

Array

Set login properties such as
username, passwo
rd and API
version

$application_name

(optional)

String

Name of your application that is
connecting to the web service


get_user_id()


Returns the ID of the user who is logged into the current session.


Syntax


new_get_user_id($session)


Example
:


To get
user ID:


new_get_user_id

array('session' => $sessionid)


Table 5:

get_user_id() arguments

Name

Type

Description

$
session

(required)

String

Session ID returned by call to
login() to start a session


get_entry()


Retrieves a single
record

based on ID.


Sy
ntax

get_entry(

$session, $module_name, $id,$select_fields, $link_name_to_fields_array)


Example
:


To retrieve contact and email address information for an Account:


get entry (

'session' => $sessionid,

'module_name' => 'Accounts',

'id' => '3d921d14
-
047f
-
c
c7d
-
1988
-
490b63592ae8',

'select_fields' =>

array('name', 'type'),

'link_name_to_fields_array' => array(

array(

'name' => 'email_addresses',

Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

5

'value' => array(

'id', 'email_address', 'opt_out', 'primary_address')

),

array(

'name' => 'contacts',

'value' =>
array(

'first_name', 'last_name', 'primary_address_city'

)

)

)

)


T
able
6
:

get_entry() arguments

Name

Type

Description

$session

(required)

String

Session ID returned by call to
login() to start a session

$module_name

(required)

String

The name of the mod
ule from
which to r
e
trieve the reco
rd


Note:

If you change the module’s
t慢 湡m攠楮 pt畤i漬 it 摯敳潴
aff散t t桥 湡me t桡t m畳t 扥
灡獳敤 i湴n t桩s met桯d

⑩d

Ereq畩r敤F

ptring

T桥 r散er摳dfa

⑳Al散瑟fi敬摳

E潰ti潮慬F

Arr慹

T桥 li獴 of fi敬摳 to 扥 r整
畲湥搠楮
t桥 r敳elts

⑬i湫彮慭敟t潟fi敬摳d慲r慹

E潰ti潮慬F

Arr慹

A li獴 of li湫nm敳⁡湤 t桥 fi敬摳dt漠
扥 r
e
t畲湥u for 敡捨 li湫n湡me


Example:

'link_name_to_fields_array' =>
array(array('name' =>
'email_addresses', 'value' =>
array('id', 'email_address
',
'opt_out', 'primary_address')))


get_entries()


Retrieves a list of records based on the specified ID’s.


Syntax


get_entries(

$session, $module_name, $ids, $select_fields, $link_name_to_fields_array)


Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

6

Example
:


To retrieve contact and email address in
formation for multiple accounts:


get_entries(

'session' => $sessionid,

'module_name' => 'Accounts',

'ids' => array(

'mastd36
8
-
c7er
-
cof8
-
16pu
-
47d57b16pets',

'3d921d14
-
047f
-
cc7d
-
1988
-
490b63592ae8'

),

'select_fields' => array('name'),

'link_name_to_fields_ar
ray' => array(

array(

'name' => 'contacts',

'value' => array(

'first_name', 'last_name', 'primary_address_city', ''

)

) ,

array(

'name' => 'email_addresses',

'value' => array(

'id', 'email_address', 'opt_out', 'primary_address'

)

)

)

)


Table
7
:

get_entr
ies
() arguments

Name

Type

Description

$session

(required)

String

Session ID returned by call to
login() to start a session

$module_name

(required)

String

The name of the module from
which to r
e
trieve the record


Note:

If you change the module’s
t慢 湡m攠
i渠nt畤i漬 it 摯敳潴
aff散t t桥 湡me t桡t m畳t 扥
灡獳敤 i湴n t桩s met桯d

⑩摳

Ereq畩r敤F

Arr慹

Array of record ID’s

⑳Al散瑟fi敬摳

E潰ti潮慬F

Arr慹

T桥 li獴 of fi敬摳 to 扥 r整畲湥搠楮
t桥 r敳elts

⑬i湫彮慭敟t潟fi敬摳d慲r慹

E潰ti潮慬F

Arr慹

A li獴 of

li湫nm敳⁡湤 t桥 fi敬摳dt漠
扥 r
e
t畲湥u for 敡捨 li湫n湡me


Example:

'link_name_to_fields_array' =>
Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

7

array(array('name' =>
'email_addresses', 'value' =>
array('id', 'email_address',
'opt_out', 'primary_address')))


get_entry_list()


Retrieves a list of
SugarBeans.


Syntax


get_entry_list(

$session, $module_name, $query, $order_by,$offset, $select_fields,
$link_name_to_fields_array, $max_results, $deleted

)


Example
:


To retrieve contact and email address information for multiple accounts:


g
et_entry_list
(

'session' => $sessionid,

'module_name' => 'Accounts',

'query' => "
name LIKE ‘%IBM’
",

'order_by' => '',

'offset' => 0,

'select_fields' =>

array('name'),

'link_name_to_fields_array' => array(

array(

'name' => 'email_addresses',

'value' => array(

'id', 'em
ail_address', 'opt_out', 'primary_address'

)

)

),

'max_results' => 2

)



Table
8
:

get_entry_list() arguments

Name

Type

Description

$session

(required)

String

Session ID returned by call to
login() to start a session

$module_name

(required)

String

The nam
e of the module from
which to r
e
trieve the record
s


Note:

If you change the module’s
Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

8

tab name in Studio, it does not
affect the name that must be
passed into this method

$query

(optional)

String

The SQL WHERE clause without
the word “where”. If left blan
k it is
the same as a ‘SELECT fields
FROM module’

$order_by

(optional)

String

The SQL ORDER BY clause
without the phrase “order by”

$offset

(optional)

String

The returned list offset from which
to start. This can be used to
implement paging via the API

$select_fields

(optional)

Array

The list of fields to be returned in
the results

$link_name_to_fields_array

(optional)

Array

A list of link names and the fields to
be r
e
turned for each link name


Example:

'link_name_to_fields_array' =>
array(array('name'

=>
'email_addresses', 'value' =>
array('id', 'email_address',
'opt_out', 'primary_address')))

$max_results

String

The maximum number of results to
return

$deleted

Integer

0 to exclude deleted records, 1 to
include


get_relationship()


Retrieves a coll
ection of beans that are related to the specified bean and, optionally, returns
relationship data.


Syntax


get_relationship(

$session, $module_name, $module_id, $link_field_name, $related_module_query,
$related_fields, $related_module_link_name_to_fields_
array, $deleted

)


Example
:


Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

9

To retrieve a contact details for a particular account and retrieve the email address and
opportunity information for those contacts:


get_relationship
(

'session' => $sessionid,

'module_name' => 'Accounts',

'module_id' => 'mast
d368
-
c7er
-
cof8
-
16pu
-
47d57b16pets',

'link_field_name' => 'contacts',

'related_module_query' => '',

'related_fields' => array(

'first_name', 'last_name', 'primary_address_city'

),

'related_module_link_name_to_fields_array' => array(

array(

'name' => 'opportu
nities',

'value' => array(

'name', 'type', 'lead_source'

)

),

array(

'name' => 'email_addresses',

'value' => array(

'id', 'email_address', 'opt_out', 'primary_address'

)

)

)

)


Table 9:

get_relationship() arguments

Name

Type

Description

$session

(require
d)

String

Session ID returned by call to
login() to start a session

$module_name

(required)

Array

The name of the modules from
which to r
e
trieve the related
records


Note:

If you change the
module’s tab name in Studio, it
摯敳潴 aff散t t桥 湡me t桡t
m畳
t 扥 灡獳敤 int漠t桩猠
m整桯e

⑭潤畬敟id

Ereq畩r敤F

ptring

T桥 fa of targ整 m潤畬攠r散er搠
t漠get t桥 r敬慴楯湳ni灳pf潲

⑬i湫_fi敬摟湡me

Ereq畩r敤F

ptring

T桥 r敬慴楯湳ni瀠湡m攠ef t桥
li湫敤 fi敬搠from w桩捨⁴漠oet畲u
r散er摳

⑲敬慴敤彭潤畬敟q略ry

E潰ti潮
慬F

ptring

T桥 灯rti潮 of t桥 tebob
捬慵獥sfr潭 t桥 pni st慴敭敮e
Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

10

used to find the related items

$related_fields

(optional)

Array

The related fields to be returned

$related_module_link_name_to_fields_array

(required)

Array

For every related bean
returned
, specify link field
names to field information.


Example:

'link_name_to_fields_array' =>
array(array('name'
=>'email_addresses', 'value' =>
array('id', 'email_address',
'opt_out', 'primary_address')))

$deleted

(required)

Integer

0 to exclude deleted reco
rds, 1
to include


get_note_attachment()


Retrieves an attachment
related to
a note.


Syntax


get_note_attachment($session,$id)


Example
:


To retrieve an attachment related to a note
:


get_note_attachment array(

'session' => $sessionid, 'id' => 'bb79c0f3
-
78e1
-
c6fc
-
2c41
-
490b636653c0')


Table 10:

get_note_attachment() arguments

Name

Type

Description

$session

(required)

String

Session ID returned by call to
login() to start a session

$id

(required)

String

The ID of the note that you
want to retrieve the at
tachment
from


get_document_revision()


In case of .htaccess lock
-
down on the cache directory, allows an authenticated user with the
appropriate permissions to download a document.

Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

11


Syntax


get_document_revision($session, $id)


Example
:


To get a document

revision:


get_document_revision array(

'session' => $sessionid, 'id' => '92acc4f4
-
8573
-
947e
-
fc60
-
49121d63eb56')


Table 11:

get_document_revision() arguments

Name

Type

Description

$session

(required)

String

Session ID returned by call to
login() to start

a session

$id

(required)

String

The ID of the document revision
that you want to retrieve the
attachment from



set_entry()


Creates or updates a record.


Syntax


set_entry($session,$module_name, $name_value_list)


Example
:


To create a new account:


se
t_entry
(

'session' => $sessionid,

'module_name' => 'Accounts',

'name_value_list' => array(

array(

'name' => 'city',

'value' => 'San Francisco'

),

array(

'name' => 'name',

'value' => 'San Francisco Giants'

)

)

);


Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

12

Table
12
:

set_entry() arguments

Name

Type

D
escription

$session

(required)

String

Session ID returned by call to
login() to start a session

$module_name

(required)

Array

The name of the module from
which to create or update the
record


Note:

If you change the module’s
t慢 湡m攠楮 pt畤i漬 it 摯敳

aff散t t桥 湡me t桡t m畳t 扥
灡獳敤 i湴n t桩s met桯d

⑮慭敟a慬略彬i獴

Ereq畩r敤F

Arr慹

Arr慹 of 湡meLv慬略 慲aay猠t漠獥t
潲o異摡t攠e慬略猠for t桥 r散erd


set_entries()


Creates or updates a list of records


Syntax


set_entries($session,$module_name, $
name_value_lists)


Example
:


To create multiple new accounts:


set_entries
(

'session' => $sessionid,

'module_name' => 'Accounts',

'name_value_list' => array(


array(

array(

'name' => 'city',

'value' => 'SFO'

),

array(

'name' => 'name',

'value' => 'Acc1'

)



),

array(

array(

'name' => 'city',

'value' => 'SFO'

),

array(

'name' => 'name',

Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

13

'value' => 'Acc2'

)

)

),

)


Table
13
:

set_entries() arguments

Name

Type

Description

$session

(required)

String

Session ID returned by call to
login() to start a session

$
module_name

(required)

Array

The name of the module from
which to create or update the
record


Note:

If you change the module’s
t慢 湡m攠楮 pt畤i漬 it 摯敳潴
aff散t t桥 湡me t桡t m畳t 扥
灡獳敤 i湴n t桩s met桯d

⑮慭敟a慬略彬i獴
s

Ereq畩r敤F

Arr慹

C潮t慩n

獥s敲慬

慲r慹
s

of
湡m支e慬略 慲r慹猠t漠獥s 潲 異摡te
v慬略猠for
敡捨
r散erd


set_relationship()


Sets a single relationship between two records.


Syntax


set_relationship(

$session, $module_name, $module_id, $link_field_name, $related_ids)


Example
:


To

set a single relationship between two records:


set_relationship(

'session' => $sessionid,

'module_name' => 'Accounts',

'module_id' => 'mastd368
-
c7er
-
cof8
-
16pu
-
47d57b16pets',

'link_field_name' => 'contacts',

'related_ids' =>

array(

'2f043319
-
7cb0
-
6bfa
-
75d
3
-
490b63fa6c08',

'c57d7598
-
42e6
-
cca8
-
a302
-
490b63118b48'

),

)


Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

14

Table
14
:

set_relationship() arguments

Name

Type

Description

$session

(required)

String

Session ID returned by call to
login() to start a session

$module_name

(required)

String

The name of the

module from
which to set the relationships to


Note:

If you change the module’s
t慢 湡m攠楮 pt畤i漬 it 摯敳潴
aff散t t桥 湡me t桡t m畳t 扥
灡獳敤 i湴n t桩s met桯d

⑭潤畬敟id

Ereq畩r敤F

ptring

T桥 fa of t桥 獰s捩fi敤 m潤畬攠
r散erd

⑬i湫_fi敬摟湡me

Ereq
畩r敤F

ptring

T桥 湡me of t桥 v慲摥f fi敬搠
r敬慴敤at漠t桥 ot桥r m潤畬e

⑲敬慴敤彩摳

Ereq畩r敤F

Arr慹

Array of ID’s to link to the
⑭潤畬敟i搠d散erd


set_relationships()


Sets multiple relationships between two records.


Syntax


set_relationships(

$sessio
n, $module_names, $module_ids, $link_field_names, $related_ids)


Example
:


To set multiple relationships between multiple beans:


set_relationships
(

'session' => $sessionid,

'module_names' => array('Accounts', 'Contacts'),

'module_ids' => array(

'mastd368
-
c7er
-
cof8
-
16pu
-
47d57b16pets',

'2f043319
-
7cb0
-
6bfa
-
75d3
-
490b63fa6c08'

),

'link_field_names' => array('contacts', 'opportunities'),

'related_ids' =>

array(

array(

'2f043319
-
7cb0
-
6bfa
-
75d3
-
490b63fa6c08'

),

array(

'52acdc25
-
6a6e
-
a574
-
6936
-
490b63fbc1df'

Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

15

)

),

)

);


Table
15
:

set_relationships() arguments

Name

Type

Description

$session

(required)

String

Session ID returned by call to
login() to start a session

$module_names

(required)

Array

The name of the modules from
which to set the relationships to


Note:

I
f you change the module’s
t慢 湡m攠楮 pt畤i漬 it 摯敳潴
aff散t t桥 湡me t桡t m畳t 扥
灡獳敤 i湴n t桩s met桯d

⑭潤畬敟id

Ereq畩r敤F

ptring

T桥 fa of t桥 獰s捩fi敤 m潤畬攠
r散erd

⑬i湫_fi敬摟湡me

Ereq畩r敤F

ptring

T桥 湡me of t桥 v慲摥f fi敬搠
r敬慴敤at漠t
桥 ot桥r m潤畬e

⑲敬慴敤彩摳

Ereq畩r敤F

Arr慹

Array of arrays for ID’s to link to the
⑭潤畬敟i搠d散er搮 T桥 湵m扥r of
獵s 慲r慹猠will m慴捨 t桥 湵m扥r
of Am潤畬敟湡m敳 y潵 灡獳sin


set_note_attachment()


Add or replace a note’s attachment.


Syntax


set
_note_attachment($session, $note)


Example
:


To add or replace a note in the Accounts module:


set_note_attachment(

'session' => $sessionid,

'note' =>
array(

'id' => 'bb79c0f3
-
78e1
-
c6fc
-
2c41
-
490b636653c0',
'related_module_id' => '3d921d1
4
-
047f
-
cc7d
-
1988
-
4
90b63592ae8',

'related_module_name' => 'Accounts'

Todo: {more params here}

)

Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

16

)
;

Table 16:

set_note_attachment() arguments

Name

Type

Description

$session

(required)

String

Session ID returned by call to
login() to start a session

$
n
ote

(required)

Array

Th
is array contains the details for
the revision object including the
‘file’ parameter that is the Base64
敮捯c敤 捯ct敮ts of t桥 摯捵浥湴


set_document_revision()


Sets a new revision for a document.


Syntax


set_document_revision($session, $document_revis
ion)


Example
:


To set a document revision:


set_document_revision(

'session' => $sessionid,

'document_revision' => array(

'id' => '8d7f0917
-
19d3
-
9f88
-
80d7
-
49121ddb62e2',



'document_name' => 'test doc',



'revision' => 'B',



'filename' => 'code.txt',

'
file' =>
'JHFzID0gJyc7DQppZiAoaXNzZXQoJF9TRVJWRVJbJ1FVRVJZX1NUUklORyddKSkgew0KCS
Rx'


)

);


Table 17:

set_document_revision() arguments

Name

Type

Description

$session

(required)

String

Session ID returned by call to
login() to start a session

$
document_re
vision

(required)

Array

This array contains the details for
the revision object including the
‘file’ parameter that is the Base64
敮捯c敤 捯ct敮ts of t桥 摯捵浥湴


Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

17

search_by_module()


Returns the ID, module name and fields for specified modules.
Currently

s
upported modules are
Accounts, Bugs, Calls, Cases, Contacts, Leads, Opportunities, Projects, Project Tasks, and
Quotes.


Syntax


search_by_module(

$user_name, $password, $search_string, $modules, $offset, $max_results)


Example
:


To get details on Accoun
ts and Contacts modules:


search_by_module(

'user_name' => 'admin',


'password' => '21232f297a57a5a743894a0e4a801fc3',


'search_string' => 'a',


'modules' => array('Accounts', 'Contacts'),


'offset' => 0,


'max_results' => 2,

)
;


Table 18:

search_by_modul
e() arguments

Name

Type

Description

$session

(required)

String

Session ID returned by call to
login() to start a session

$user_name

(required)

String

Sugar username to authenticate
with

$password

(required)

String

The password for the user

$search_stri
ng

(required)

String

The string to represents the query
to search by

$modules

(required)

String

The list of modules to query

$offset

(optional)

Integer

The returned list offset from which
to start. This can be used to
implement paging via the API

$max_
results

(optional)

Integer

The maximum number of results to
return


get_server_info()


Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

18

Returns server information such as version, flavor, and gmt_time.


Syntax


get_server_info()


Table 19:

get_server_info
() arguments

Name

Type

Description

N/A

N/A

N/A


get_module_fields()


Retrieves variable definitions (vardefs) for fields of the specified module.


Syntax


get_module_fields($session, $module_name, $fields)


Example
:


To get vardefs from the Bugs module:


get_module_fields

array(

'session' => $sessionid
,

'module_name' => 'Bugs'

);


Table 20:

get_module_fields() arguments

Name

Type

Description

$session

(required)

String

Session ID returned by call to
login() to start a session

$module_name

(required)

String

Name of the module from which to
retrieve the
vardef field set from



Interfaces


With the 5.5 release of the updated web services we are continuing to support a SOAP interface
as well as include the addition of a new REST based one. These will be described in more
detail in this section.


SOAP Over
view


Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

19

SOAP is probably the most
used
web

services protocol. It provides a way of exchanging
structured information of application functionality. A SOAP interface can be defined by its WSDL
(Web Service Description Language) file.
We will be remaining bac
kwards compatibility of our
old SOAP Interface as well as creating a new version (Version 2) to support the new list of API
calls.
To access WSDL for version 2 of the Sugar Web Services API you can read it by going to
this URL in your browser:
http://sugar_root_url/service/v2/soap.php?wsdl
. The WSDL file will
give complete explanation of all the methods with input/output data type. After looking through
the WSDL file you can take a look at e
xamples/SugarFullTest_Version2.php for more examples
on usage.



Figure 1: SOAP Web Services API Call Flow



REST Overview


New to the Sugar Web Services framework in the 5.5
release

is a REST interface. This has
been one of the more requested additions
to the service as it adds a lighter weight way for
developers to gain access to data in a system.
REST is preferable for higher transactional web
Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

20

services implementations as well as browser client side implementations where all rendering
happens in the br
owser off of JSON formatted responses.
To connect to the REST interface in
the new web services framework you will connect to the following URL:
http://sugar root
url/service/v2/rest.php
.


We have provided JOSN/PHP Serialize as input/output data type for
the REST protocol. Those
data type files can be located in the ‘<sugar app root>/service/core/REST’ directory. In that
directory you will find two files for those two types(SugarRestJSON.php and
SugarRestSerialize.php).


The framework will allow you to d
efine your own data type. To achieve this you will need to
follow the following steps:




Create a corresponding SugarRestCustomDataType.php in the ‘<sugar app
root>/service/core/REST’ directory



Override the
generateResponse()

and
serve()

functions


serve()

: takes the appropriate data type and decodes/
unserialize
s it based on the input type.


generateResponse()

: will encode/
serialize

the data based on the output type.


Once you add your new data/response type to the framework you will need to be able to ma
ke
API calls setting input/output to your new types.


For an example look at ‘<sugar app root>/service/test.html file at the
getRequestData()

function
which sets the URL params
input_type

and
response_
type

to
json
.


The input data in the request from the b
rowser via javascript to the server will be in json format
and the response data from server will also be in json format. You can have mixed data type for
input and output (ex: json as input_type and searize as response_type).


Figure 2: REST Web Services
API call Flow


Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

21




5.5 Web Services
Architecture


This section will go into detail regarding the various com
ponents of the new web services as
well as

how
they are organized.


Versioning


By supporting backwards compatibility for Version 1 of our web servi
ces in
5.5
we
will introduc
e

of a versioning and extensibility framework in Sugar 5.5.


All the classes live in a
service

directory. The
service

director
y contains following information:




core

:
directory contains all the core classes.



REST

:

directory co
ntains all the REST protocol (ex. JOSN, php serialize) classes.



v
2

:

directory contains all the version specific classes for SOAP and REST
implementation.


Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

22

To access the new version (Version 2) of the
web services you will use

the URL
http://sugar_root_url/service/v2/soap.php

to connect
. In this file we
will define following
variables:




$webservice_class

:
service class responsible for soap services
-

SugarSoapService2



$webservice_path

:

The l
ocatio
n of the service class
-

v
2/
SugarSoapService2
.php



$registry_class

:

Responsible for registering all the complex data types and functions
available to call



$registry_path

:

The location of registry class
-

service/v2/registry.php



$webservice_impl_class

:
Th
e implementation class for all the functions



$location

:
The location of soap.php

to connect to(ie:

'/service/v2/soap.php')


The file which is responsible for instantiating service class and calling different helper methods
based on the values of above var
iables is core/webservice.php.


Web Services Hierarchy


Following is the complete class hierarchy for the web services implementation along with all the
class attributes and operations.


Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

23


Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

24

Extending in an Upgrade Safe Manner


Before the release of 5.5 it w
as only possible to add new web services functionality by modifying
out of box core files. Each subsequent upgrade would then require the end Sugar user to check
to make sure the newest patch/upgrade being applied did not have any files in conflict. In
Ve
rsion 2 we have provided an extensible framework to allow a developer to add and distribute
new web services functionality without the need to worry about merging code with each
patch/
upgrade.


The

steps needed to create your ow
n version which is upgrade s
afe are:


1.

Create a v2_1 directory

in the services directory


2.

P
rovide you own registry.php
file
in your new directory
(ex:

customregistry.php
)
.
Example customregistry.php file contents would look like this:


<?php

require_once('service/v2/registry.php');


class
customregistry

extends registry{




public function __construct($serviceClass)

{

parent::__construct($serviceClass);


} //
end contructor fuction







protected function registerFunction()

{



parent::registerFunction();



$this
-
>serviceClass
-
>reg
isterFunction(




'get_entry',




array(

'session'=>'xsd:string',

'module_name'=>'xsd:string',

'id'=>'xsd:string'

),




array('return'=>'xsd:string')

);



} //
end registerFunction

} //
end customregistry
cla
ss


Lets look at our example custom function r
egisterFunction.




We call parent::

registerFunction
() to include all the out of box functions.



Next we declare
$this
-
>serviceClass
-
>registerFunction
(name, input, output). This allow
you to define your new custom functions input/output parameters.


3.

P
rovi
de you own implementation class which extends from the base implementation
class.
For example:


Sugar 5.5 Web Services
-

Design Overview Document


Copyright © 2009

SugarCRM, Inc. All rights reserved.

25

<?php

require_once('service/core/SugarWebServiceImpl.php');


class SugarWebServiceImpl_v2_1

extends SugarWebServiceImpl

{




function get_entry($session, $modu
le_name, $id)

{



return
$id
;


} //
end get_entry
fn



} //
end implementation
class


4.

Provide your soap.php or rest.php file and initialize all required variables.
E
xample
s

would be:


Example soap.php

(To be accessed at
http://sugar root url /service/v2_1
/soap.php
):


<?php

Chdir(‘../’)

//
based on how deep you have defined your
v2_1 directory


$webservice_class = 'SugarSoapService2';

$webservice_path = 'service/v2/SugarSoapService2.php';

$registry_class = '
customregistry

';

$registry_path = 'service/v2_1
/
customregistry
.php';

$webservice_impl_
class = 'SugarWebServiceImpl_v2_1
';

$
location

=

'/service/v2_1
/soap.php';

require_once('../core/webservice.php');

?>


Example rest.php

(To be accessed at
http://sugar root url/service/v2_1/rest.php
)
:


<?php

Chdir(‘../’
)

// based on how deep you have defined your v2_1 directory

$webservice_class = 'SugarRest
Service2';

$webserv
ice_path = 'service/v2/SugarRest
Service2.php';

$registry_class = '
customregistry

';

$registry_path = 'service/v2_1
/
customregistry
.php';

$webservi
ce_impl_
class = 'SugarRestServiceImpl_v2_1
';

$
location

=

'/service/v2_1/rest
.php';

require_once('../core/webservice.php');

?>




This concludes the
second

draft of the 5.5 web services overview. This document will be
continually updated over the up and co
ming weeks. Each major update will be posted for your
consumption and feedback.