Добрый день всем читателям блога. Сегодня мы начинаем изучение CRM WEB API.
Начнем с краткого обзора всех функций SugarCRM, их параметров и назначения.
Список функций:
login ()
logout ()
seamless_login ()
get_user_id ()
get_entry ()
get_entries ()
get_entry_list ()
get_relationships ()
get_note_attachment ()
get_document_revision ()
set_entry ()
set_entries ()
set_relationship ()
set_note_attachment ()
set_document_revision ()
search_by_module ()
get_server_info ()
get_module_fields ()
login($user_auth, $application_name) — авторизация в SugarCRM и создание сессии.
Параметры функции:
$user_auth — массив пользовательской информации с логином, паролем и используемой версией протокола. Пароль должен быть зашифрован в md5.
Пример:
$user_auth => array( 'user_name' => 'admin', 'password' => '21232f297a57a5a743894a0e4a801fc3', 'version' => '2' ),
$application_name — это просто имя вашего приложения, которое обращается к ЦРМ. Используется только для логирования, указывайте любое.
В случае успешной авторизации в ответ мы получаем имя пользователя(name), его id (user_id), валюту по умолчанию и, самое главное, — номер сессии(id), который нужно обязательно сохранить для всех последующих запросов. Далее id сессии сохраним в переменной $session и в этой статье используем его под этим же именем без дальнейших объяснений.
P.S. Данную информацию получаем только при использовании REST протокола, при использовании SOAP в ответ приходит только id сессии.
logout($session) — выход из CRM и завершение сессии.
seamless_login($session) — используется для Sugar Offline Client. Это функция только PRO версии.
get_user_id($session) — получить id текущего пользователя.
get_entry($session, $module_name, $id, $select_fields, $link_name_to_fields_array) — получить запись на основании ее уникального id.
Параметры функции:
$module_name — имя модуля, содержащего нужную запись;
$id — id записи (во всех стандартных модулях это 36-значный varchar);
$select_fields — массив со списком полей, необходимых для извлечения. Данный параметр можно не передавать, в данном случае CRM вернет значения всех полей;
$link_name_to_fields_array — получить поля из связанного модуля. Для связи в системе используется поля типа link. Как раз имя этого поля мы должны использовать.
Пример:
get_entry (
'session' => $sessionid,
'module_name' => 'Accounts',
'id' => '3d921d14-047f-cc7d-1988-490b63592ae8',
'select_fields' =>
array('name', 'type'),
)
get_entries($session, $module_name, $ids, $select_fields, $link_name_to_fields_array) — получить массив записей по переданным $ids. Останавливаться подробно на ней не будем.
Функция полностью аналогична предыдущей get_entry, за исключением того, что в $ids у нас массив id.
get_entry_list($session, $module_name, $query, $order_by, $offset, $select_fields, $link_name_to_fields_array, $max_results, $deleted ) — получить список (list) записей указанного модуля с переданным условием.
Параметры функции:
$module_name — имя модуля;
$query — фильтр для извлечения записей(в виде sql запроса). Например: «name LIKE '%IBM%'». Таким образом извлечем все записи в имени которых присутствует IBM;
$order_by — параметр сортировки. Например: «name DESC»;
$offset — сколько записей с начала пропустить;
$select_fields, $link_name_to_fields_array — полностью аналогичны параметрам из предыдущей функции get_entry;
$max_results — максимальное количество записей для извлечения. Если не передан, берется соответствующий параметр из настроек SugarCRM (по умолчанию 20);
$deleted — 0: не удаленные записи, 1: удаленные записи. Этот параметр можно не передавать, если вам не нужно отображать удаленные записи.
Пример использования этой функции в следующей статье.
get_relationships($session, $module_name, $module_id, $related_module, $related_module_query, $deleted) — загрузить информацию из связанного модуля.
Все параметры мы рассматривали в предыдущих функциях. Пример использования этой функции в следующей статье.
get_note_attachment($session,$id) — получить прикрепление к заметке.
В данном случае $id — это id заметки.
Пример:
get_note_attachment( 'session' => $sessionid, 'id' => 's5gvd0f3-67fv-bn6m-4dsv-490bdsd6fdtr' )
get_document_revision($session, $id) — функция, аналогичная предыдущей, только для работы с модулем документы.
Все приведенные выше функции предназначены для получения какой-либо информации из CRM. И практически все эти функции имеют аналоги для передачи данных из нашего приложения в CRM.
set_entry($session, $module_name, $name_value_list) — создать или изменить запись в CRM.
$name_value_list — это массив, каждый элемент которого, тоже, в свою очередь, массив из двух элементов с ключами name и value, где name — это имя поля, а value — его значение.
Пример:
set_entry(
'session' => $sessionid,
'module_name' => 'Contacts',
'name_value_list' => array(
array(
'name' => 'name',
'value' => 'SugarTalk'
),
)
);
В данном примере мы создали новую запись с именем SugarTalk. Если нам необходимо изменить запись, то к необходимым параметрам мы добавляем id записи для обновления.
set_entry(
'session' => $sessionid,
'module_name' => 'Contacts',
'name_value_list' => array(
array(
'name' => 'id',
'value' => 's5gvd0f3-67fv-bn6m-4dsv-490bdsd6fdtr',
),
array(
'name' => 'name',
'value' => 'SugarCRM WEB',
),
)
);
Теперь мы уже не создаем новую запись, а обновляем запись с заданным id.
set_entries($session,$module_name, $name_value_lists) — создать или изменить записи.
Функция полностью аналогична предыдущей. Только теперь в $name_value_lists передается сразу массив для добавления или обновления записей.
set_relationship($session, $module_name, $module_id, $link_field_name, $related_ids) — Устанавливает связь (relationship) между двумя записями.
Пример:
set_relationship(
'session' => $sessionid,
'module_name' => 'Accounts',
'module_id' => '4аеtd5np-cg5t-cof8-fb5h-4tfv5ythpets',
'link_field_name' => 'contacts',
'related_ids' =>
array(
'2f043319-7cb0-6bfa-75d3-490b63fa6c08',
'c57d7598-42e6-cca8-a302-490b63118b48'
),
)
В данном примере мы связываем два контакта, имеющие соответствующие id, с контрагентом.
set_relationships($session, $module_names, $module_ids, $link_field_names, $related_ids) — аналогичная функция для установки сразу нескольких разных связей.
set_note_attachment ($session, $note) и set_document_revision ($session, $document_revision) — очень схожи, и позволяют загрузить документ или заметку.
Разберем подробнее работу функции set_document_revision ($session, $document_revision)
Параметры:
$document_revision — это массив из следующих параметров: id документа (если необходимо обновить документ), имя документа, имя файла и сам контент файла в кодировке base64.
Пример из документации SugarCRM:
set_document_revision(
'session' => $sessionid,
'document_revision' => array(
'id' => '8d7f0917-19d3-9f88-80d7-49121ddb62e2',
'document_name' => 'test document',
'revision' => 'B',
'filename' => 'test.txt',
'file' => 'fdgh754hjnfdbsy56tgefdshgt8765t4wesygdfbGHfd574tegrdf'
)
);
search_by_module($user_name, $password, $search_string, $modules, $offset, $max_results) — функция поиска строки в указанных модулях.
Параметры:
$user_name — имя пользователя;
$password — пароль пользователя (в md5);
$search_string — строка поиска;
$modules — массив с именами модулей, в которых будет осуществляться поиск;
$offset — сдвиг от начала записей (по умолчанию 0);
$max_results — максимальное количество возвращаемых записей (limit в sql).
get_server_info() — возвращает информацию о SugarCRM: версию, редакцию (CE, PRO, ENT), текущий часовой пояс и т.д.
get_module_fields($session, $module_name) — возвращает описание всех полей, используемых у вас в модуле: их название, тип, label и т.д.
Пример:
get_module_fields( 'session' => $sessionid, 'module_name' => 'Contacts' );
Итак, мы разобрали используемые фукнции и их параметры. Если кому-то нужна более подробная информация, скачиваете документ «5.5 web services overview».
К сожалению, в документации возможны некоторые ошибки и опечатки 
. Я уже несколько находил. Если кто-то посоветует более грамотный док, то обязательно поменяю данный документ.
Теперь возникает вопрос, как всем этим пользоваться? Основные принципы использования SugarCRM WEB API обязательно разберем в следующей статье данного цикла.
Высказать своё мнение о статье Вы можете в комментариях, если Вас интересуют какие либо вопросы или дополнения, то обсуждение по данной теме доступно на нашем форуме.
Рубрики: 
Теги:
такой вопрос.
Есть метод — $link_name_to_fields_array — получить поля из связанного модуля. Для связи в системе используется поля типа link. Как раз имя этого поля мы должны использовать. Так вот пишу
$linkArr = array (array ('name' => 'opportunities', 'value' => array ('id', 'name', 'amount')));
$response = $this->client->get_entry_list ($this->sessionId, 'Contacts', $filter,'contacts.date_entered DESC',0, array ('id','first_name', 'last_name',$linkArr,2000,0);
Так вот проблема в том что в Sugar 6.2 Profession выдает ошибку как только дополнительный модуль не прикручивай. Может быть кто сталкивался с подобной проблемой!??!?!
Смотрите в логах что за ошибка. И кидайте логи с ошибкой в студию
Итак, после задания настроить приложение с SugarCrm 6.2.0 Pro выявил следующие недостатки протокола SOAP:
1. Для модуля contacts «выгребает» почему то с повторяющимися id записи и кол-во «выгребки» максимум 2200 штук (вероятно нет group by contacts.id), и это при том что 2/3 повторяющихся, т.е реальное кол-во меньше тысячи. Это не получилось обойти ни как.
2. Вообще не работает 'link_name_to_fields_array' для get_entry_list.
В связи с этим, перешел на протокол REST c использованием curl. Все работает отлично. И количество «выгребки» из контактов 3300 без повторяющихся id (вероятно есть group by contacts.id)
Я тоже использую протокол REST в своих php и python приложения для работы с SugarCRM.
Насчет ограничения количества выборки странно, сложно так сказать как вы загружаете записи,
возможно там происходит вызов retrive для каждой записи, что вызывает отдельный запрос к бд,
и вследствие этого вы доходите до ограничения запросов к БД, которые ограничивает шугаровский database manager.
Попробуйте в секции в config.php в секции 'resource_management'->'special_query_modules' добавить модуль с каким вы пытаетесь работать, или же увеличить 'resource_management'->'default_limit'
Спасибо, очень полезная статья.
Правда, кое-что уже в ней устарело ...
Думаю, в статье стоит упомянуть, что функции типа set_ возвращают объект, содержащий в тос числе и id новой записи.
Сам дошёл этого интуитивно ))) Но до этого не знал, как получить этот ай ди
Сейчас пишу класс для связи сторонней системы с SugarCRM , пишу на версии 6.2.1 CE
Возникла проблема. Хочу связать email адрес с контактом, но получаю
Fatal error: Uncaught SoapFault exception: [Client] looks like we got no XML document in … далее описание вызванного метода
Вот мой код:
Но вот код, работающий штатно, т.е. связь контакта с контрагентом:
Не оставьте в беде! Заказчики требуют...
Не скажу за последние версии, времени нет проверить.
Раньше всегда делал самым простым способом. Просто для контакта исользовал поле email1,
при сохранении автоматически создавался email и связь с ним:
$client->set_entry($session_id, 'Contacts', array( array("name" => 'first_name',"value" => 'Vasya'), array("name" => 'last_name',"value" => 'Batareikin'), array("name" => 'email1',"value" => '[email protected]') ));А что делать, если мне надо получить тут же id данного имейла, чтобы прикрепить его ещё и к контрагенту?
Было бы круто иметь API для работы с таблицей email_addr_bean_rel напрямую
Ничего не мешает вам дописать это API,
мне обычно тоже для связи с внешними приложениями не достаточно, или не удобно работать с их API,
я обычно всегда расширяю API под себя, SugarCRM это позволяет в upgrade safe.
Не разбирался с расширением SOAP, так как работаю с REST, который точно очень легко расширить, буквально за десять-двадцать минут, написать функцию которая бы прикрепляла ваш email к нужным контрагентам, контактам, да и вообще делала все то как вы хотите )
Давно уже подумываю написать статью по расширению WEB API, но время не позволяет.
Как раз кое-что мешает — техническое задание по проекту предусматривает только написание класса, спомощью которого можно подсоединяться и делать дело. Sugar будет стоять не на моём севере, на заказчик будет подключать класс для связи двух своих систем.
Сам в качестве CRM использую Drupal =)
Спасибо! Фишка с email1 прокатила для контактов.
Но...
get_relationship для email и contact тоже выдаёт похожую системную ошибку...
А get_entry для контакта показывает только сами адреса, а не их id
Всё, я разобрался! Спасибо спасибо!
а где ж брать $module_id для get_relationships?
$response = $client->get_available_modules ($session);
echo '!'.implode (' | ',$response->modules).'!';
Пардон, это получим имена модулей.
id элементов можно посмотреть:
1. напрамую в базе данных,
2. через саму систему в url к элементу
3. получить в результате get_entry (s), get_entry_list
В комментариях принимаются только ваши отзывы. если Вас интересуют какие либо вопросы или дополнения, то обсуждение по данной теме доступно на нашем форуме.