REST for the Traveling Salesman: Using Google Data on Salesforce.com

Lane LiaBraaten, Google Developer Programs
Listopad 2007 r.

Wprowadzenie

Salesforce.com i Google udostępniają popularne aplikacje „Software as a Service” (oprogramowanie jako usługa). Obie organizacje udostępniają interfejsy API, które umożliwiają deweloperom dostęp do dużych zbiorów danych, na których opierają się te aplikacje. Połączenie obu zestawów interfejsów API otwiera nowe możliwości. G Suite jest coraz częściej używany w firmach, a Salesforce.com stworzył rozbudowaną platformę do tworzenia niestandardowych aplikacji biznesowych. Deweloperzy (czyli Ty!) mają więc wiele możliwości łączenia potencjału Google i Salesforce.com.

Z tego artykułu dowiesz się, jak używać interfejsów Google Data API typu RESTful, aby zacząć tworzyć mashupy dla przedsiębiorstw, nawet jeśli dopiero zaczynasz korzystać z platformy Salesforce.com lub protokołu Google Data. Pomogę Ci skonfigurować środowisko deweloperskie, zainstalować istniejącą aplikację łączącą Salesforce.com i Google, a potem napisać własną.

Hello, Salesforce.com!

Jeśli tak jak ja dopiero zaczynasz korzystać z Salesforce.com, musisz najpierw zarejestrować konto dewelopera w ADN, czyli Apex Developer Network. Konto dewelopera zapewnia dostęp do w pełni funkcjonalnego konta Salesforce.com, a także do wiki Apex i forów dyskusyjnych.

Następnie pobierz Apex Toolkit for Eclipse. Zestaw narzędzi wymaga Javy 1.5 i Eclipse 3.2.2 lub nowszych wersji. Jeśli znasz środowisko Eclipse, witryna aktualizacji oprogramowania dla pakietu narzędzi to http://www.adnsandbox.com/eclipsetoolkit/10.0/. Jeśli nie znasz wtyczek Eclipse lub podczas instalacji wystąpią problemy, na stronie wiki Apex znajdziesz szczegółowe instrukcje instalacji.

Po zainstalowaniu pakietu narzędziowego możesz uzyskać dostęp do treści pomocy dotyczących Apex, które są zintegrowane z systemem pomocy Eclipse. Aby wyświetlić te treści w Eclipse, kliknij Help | Help Contents | Apex Toolkit for Eclipse (Pomoc | Zawartość pomocy | Apex Toolkit for Eclipse). Jednym z tych zasobów jest samouczek wprowadzający, z którego dowiesz się, jak utworzyć nowy projekt oraz dodać elementy S-Controls, klasy i wyzwalacze. Jeśli nie masz jeszcze doświadczenia z kodem Apex, przed przejściem dalej zapoznaj się z tym samouczkiem i utwórz projekt Apex.

Eksportowanie wydarzeń do Kalendarza Google

Ron Hess napisał aplikację Google Calendar Mash-up, która umożliwia eksportowanie wydarzeń z Salesforce.com do Kalendarza Google. Ron napisał też artykuł, w którym wyjaśnia, jak działa jego mashup. Aplikacja Arkusze Google, którą pokażę Ci, jak utworzyć, jest wzorowana na połączeniu Kalendarza Google Rona. Dzięki, Ron!

Jeśli jesteś zaawansowanym użytkownikiem Salesforce.com, prawdopodobnie możesz zintegrować i używać aplikacji Kalendarz Google Rona bez żadnych instrukcji. Na początku potrzebowałem trochę pomocy, więc oto co zrobiłem, aby zobaczyć aplikację Rona w działaniu.

  1. Zainstaluj aplikację:
    • Otwórz stronę Google Calendar Mash-up i kliknij Pobierz.
    • Wpisz dane logowania do ADN i kliknij Dalej.
    • Przeczytaj Warunki i kliknij Dalej.
    • Kliknij Dalej na stronie „Sprawdź zawartość opakowania”.
    • Wybierz poziom zabezpieczeń i kliknij Dalej.
    • Kliknij Zainstaluj.
  2. Konfigurowanie serwera proxy AJAX w Salesforce.com
    • W menu „Konfiguracja administracyjna” kliknij Ustawienia zabezpieczeń | Ustawienia witryny zdalnej.
    • Kliknij Nowa witryna zdalna.
    • Wpisz Google jako „Nazwę witryny zdalnej”, a jako „Adres URL witryny zdalnej” użyj https://www.google.com.
    • Kliknij Zapisz.
  3. Dodaj przycisk „Dodaj do Google” na stronie ze szczegółami wydarzenia:
    • W menu „Konfiguracja aplikacji” kliknij Dostosuj | Aktywności | Układy stron wydarzeń.
    • W wierszu „Układ wydarzenia” kliknij Edytuj.
    • Kliknij dwukrotnie obszar „Przyciski na stronie szczegółów”.
    • Zaznacz „Dodaj do Google” i kliknij strzałkę w prawo (>), aby dodać przycisk.
    • Kliknij OK.
    • Na stronie „Właściwości układu strony” kliknij Zapisz.
  4. Eksportowanie wydarzenia
    • Aby wyświetlić kalendarz, w lewym górnym rogu kliknij Strona główna.
    • Jeśli nie masz żadnych wydarzeń, kliknij Nowe wydarzenie, aby je utworzyć.
    • Kliknij zdarzenie, aby wyświetlić stronę Szczegóły zdarzenia.
    • Kliknij przycisk Dodaj do Google.
    • Kliknij OK w oknie alertu JavaScript.
    • Zaloguj się za pomocą nazwy użytkownika i hasła Google.
    • Kliknij Przyznaj dostęp, aby przyznać aplikacji Salesforce uprawnienia do zapisu w Kalendarzu Google.
    • Wyświetl wydarzenie w Kalendarzu Google.

Tworzenie aplikacji Arkuszy Google

Pewnie masz już dość klikania stron Salesforce.com i chcesz napisać trochę kodu. Ponownie uruchom Eclipse. Zobaczysz, że utworzony przez Ciebie projekt Apex zawiera teraz elementy S-Controls aplikacji Kalendarz Google Rona. Dzieje się tak, ponieważ pakiet Apex Toolkit for Eclipse jest stale synchronizowany z Salesforce.com. To całkiem fajne, prawda?

Możesz utworzyć własną aplikację Google Data, wykorzystując niektóre funkcje aplikacji Mash-up Kalendarza Google, takie jak kontrolki uwierzytelniania. W pozostałej części tej sekcji pokażę Ci, jak utworzyć aplikację, która eksportuje kontakty z Salesforce.com do arkusza kalkulacyjnego Google.

Publikowanie prostego elementu S-Control

S-Control to plik hostowany przez Salesforce.com i wykonywany w przeglądarkach internetowych, gdy użytkownicy uzyskują dostęp do Twojej aplikacji. Kontrolka S-Control może zawierać dowolny typ treści, które można wyświetlić lub uruchomić w przeglądarce internetowej, np. HTML, CSS lub JavaScript.

W przypadku połączenia Salesforce.com i Google jest wiele elementów, więc najpierw dodałem przycisk „Eksportuj do Google” na stronie listy kontaktów, który wywołuje prosty element S-Control. Chciałem się upewnić, że wszystko działa prawidłowo, zanim zacznę pisać kod JavaScript.

W projekcie Apex kliknij prawym przyciskiem myszy folder „S-Controls” i wybierz Apex | New S-Control (Apex | Nowy S-Control). Nadaj nowemu elementowi S-Control etykietę i nazwę export_contacts, pozostaw typ Niestandardowy HTML i kliknij Zakończ.

Nowy element S-Control będzie zawierał szkieletowy plik HTML. W sekcji <head> dodasz sporo kodu JavaScript, ale najpierw możesz wypełnić sekcję <body>, aby użytkownik widział coś podczas eksportowania kontaktów. Skopiuj ten kod HTML do treści elementu S-Control, aby wyświetlać „kropki oczekiwania” i logo Arkuszy Google:

<div id="waiting" align="center" />
  <img src="/img/icon/home32.png" height="64" width="64" />
  <img src="/img/waiting_dots.gif" alt="Please wait..." title="Please wait..." height="25" width="196" />
  <img src="http://docs.google.com/images/doclist/logo_docs.gif" />
  <p><h3>Exporting contacts to Google Spreadsheets, please wait...</h3></p>

</div>

Teraz możesz opublikować S-Control i skonfigurować przycisk, który będzie go wywoływać.

  1. Opublikuj plik S-Control za pomocą Eclipse:
    • Kliknij prawym przyciskiem myszy projekt Apex i wybierz Apex | Synchronize with Salesforce (Apex | Synchronizuj z Salesforce).
    • W drzewie katalogów znajdź nowy element S-Control, kliknij go prawym przyciskiem myszy i wybierz Zastąp zdalnie i opublikuj na serwerze.
    • Jeśli nie możesz znaleźć kontrolki S-Control, narzędzia Apex Toolkit mogły już ją przesłać, ale warto użyć perspektywy synchronizacji, aby mieć pewność, że na serwerze działa najnowszy kod.
  2. W interfejsie Salesforce.com zdefiniuj przycisk, który będzie wywoływać ten S-Control:
    • W menu „Konfiguracja aplikacji” kliknij Dostosuj | Kontakty | Przyciski i linki.
    • W sekcji „Niestandardowe przyciski i linki” kliknij Nowy.
    • Wpisz Eksportuj do Google jako etykietę i pozostaw Eksportuj_do_Google jako nazwę.
    • Jako typ wyświetlania wybierz „Przycisk listy”.
    • Jako źródło treści wybierz „Niestandardowy element S-Control”.
    • W sekcji „Zachowanie” wybierz „Wyświetl w istniejącym oknie z paskiem bocznym”.
    • W menu niestandardowych elementów sterujących wybierz „export_contacts”.
  3. Dodaj przycisk do listy kontaktów:
    • W menu „Konfiguracja aplikacji” kliknij Dostosuj | Kontakty | Układy wyszukiwania.
    • W wierszu „Widok listy kontaktów” kliknij Edytuj.
    • Wyróżnij „Eksportuj do Google” i kliknij strzałkę w prawo (>), aby dodać przycisk.
    • Kliknij Zapisz.
  4. Wypróbuj go:
    • Kliknij kartę Kontakty.
    • Wybierz „Wszystkie kontakty” jako widok i kliknij Dalej.
    • Kliknij nowy przycisk Eksportuj do Google.
    • Obserwuj „waiting_dots”, ale nie oczekuj niczego więcej.

Praca z Arkuszami Google

Jeśli zajrzysz do źródła mash-upu Kalendarza Google, zobaczysz, że plik gcal_snippet.scf zawiera abstrakcję serwera Kalendarza Google. Aby korzystać z Arkuszami Google, musisz utworzyć podobny plik na serwerze Arkuszy Google. Wykorzystałem kod Rona Hessa do używania serwera proxy AJAX Salesforce.com i uwierzytelniania za pomocą Google AuthSub. Zastąpiłem też funkcję, która zapisuje zdarzenia w Kalendarzu Google, funkcją zapisującą informacje w Arkuszach Google. Pełny kod źródłowy tego pliku jest dostępny w pliku gspreadsheet_snippet.scf.

Następnie dodałem JavaScript do elementu S-Control export_contacts.scf, aby wysyłać zapytania do Salesforce.com o dane kontaktowe i zapisywać je w arkuszu kalkulacyjnym Google. Wyodrębnianie danych z Salesforce.com jest proste. Wystarczy utworzyć zapytanie i podać funkcję wywołania zwrotnego, która zostanie wykonana po zwróceniu danych. Na przykład:

  var query = 'Select FirstName, LastName, Phone From Contact';
  var queryResult = sforce.connection.query(query, queryCallback);

Po uzyskaniu informacji kontaktowych z Salesforce.com musisz określić, gdzie je wyeksportować. W protokole RESTful Google Data każdy arkusz kalkulacyjny można zidentyfikować za pomocą unikalnego adresu URL. Listę arkuszy kalkulacyjnych użytkownika (wraz z powiązanymi adresami URL) możesz uzyskać, wysyłając zapytanie do adresu URL metafeedu: http://spreadsheets.google.com/feeds/spreadsheets/private/full. Poniższa metoda iteruje po tych arkuszach kalkulacyjnych, szukając arkusza o określonym tytule. Gdy znajdzie odpowiedni arkusz kalkulacyjny, najpierw pobierze listę arkuszy, a potem zwróci adres URL pliku danych komórek pierwszego arkusza.

function getCellFeedUrl() {
  var SPREADSHEET_TITLE = 'Salesforce.com Contacts';
  var WORKSHEET_REL = 'http://schemas.google.com/spreadsheets/2006#worksheetsfeed';
  var CELLSFEED_REL = 'http://schemas.google.com/spreadsheets/2006#cellsfeed';

  // Query to find the spreadheet called "Salesforce.com Contacts"
  var spreadsheets = g.getFeed('http://spreadsheets.google.com/feeds/spreadsheets/private/full');
  var entries = g.getEntryList(spreadsheets);
  for (var e in entries) {
    if (g.getTitle(entries[e]) == SPREADSHEET_TITLE) {
      var worksheetsFeedUrl = g.link(entries[e],WORKSHEET_REL);
      var worksheets = g.getFeed(worksheetsFeedUrl);
      var worksheetEntries = g.getEntryList(worksheets);
      return g.link(worksheetEntries[0], CELLSFEED_REL);
    }
  }
}

Więcej informacji o dostępnych w interfejsie Google Spreadsheets Data API plikach danych znajdziesz w przewodniku.

Funkcja queryCallback używa metody getCellFeedUrl, aby znaleźć adres URL pliku danych komórek potrzebny do wysyłania żądań aktualizacji komórek, a następnie zapisuje informacje kontaktowe w komórce po komórce.

function queryCallback(queryResult) {
  var cellFeedUrl = getCellFeedUrl();
  var contacts = queryResult.getArray('records');
  for (var i=0; i<contacts.length; i++) {
    g.updateCell(cellFeedUrl, i+1, 1, contacts[i].LastName + ", " + contacts[i].FirstName);
    g.updateCell(cellFeedUrl, i+1, 2, contacts[i].Phone);
  }
  
  jumpback(); // Return to the contacts page when your done
}

Metoda updateCell występuje w kontrolce S-Control gspreadsheet_snippet.scf. Metoda pobiera adres URL edycji komórki w danym wierszu i kolumnie, a następnie wysyła komunikat HTTP PUT zawierający reprezentację danych Google zaktualizowanej komórki:

GoogleSpreadsheet.prototype.updateCell = function(cellsFeedUrl, row, column, content ) {
  var cellEntry = this.getFeed(cellsFeedUrl+'/R'+row+'C'+column);
  var cellEditUrl = this.link(cellEntry,'edit');

  var newCellEntry = "<atom:entry xmlns:atom='http://www.w3.org/2005/Atom'>" +
      "<atom:category scheme='http://schemas.google.com/spreadsheets/2006' " +
      "term='http://schemas.google.com/spreadsheets/2006#cell' />" +
      "<gs:cell xmlns:gs='http://schemas.google.com/spreadsheets/2006' " +
      "row='" + row + "' col='" + column + "' inputValue='" + content + "' />" +
      "</atom:entry>";

  this.putEntry(cellEditUrl, newCellEntry);
}

Więcej informacji o aktualizowaniu komórek za pomocą interfejsu Google Spreadsheets Data API znajdziesz w Przewodniku dla deweloperów.

Interfejs Google Spreadsheets Data API używa subdomeny https://spreadsheets.google.com, więc zanim powyższy kod zacznie działać, musisz skonfigurować serwer proxy AJAX w Salesforce.com i dodać https://spreadsheets.google.com.

Musisz też otworzyć Dokumenty Google i utworzyć nowy arkusz kalkulacyjny, w którym będą przechowywane dane. Zapisz go jako Kontakty Salesforce.com.

Po przesłaniu tych elementów S-Control możesz wyeksportować informacje kontaktowe do arkusza kalkulacyjnego Google. A w drugą stronę? Dzięki nowej wiedzy o interfejsach API danych Google i Salesforce.com możesz też napisać kod, który zaimportuje informacje o kontaktach z Arkuszy Google do Salesforce.com.

Podsumowanie

Ten artykuł zaledwie zarysowuje temat, ale teraz, gdy znasz już platformę Salesforce.com i interfejsy Google Data API, pomyśl o wszystkich aplikacjach, które możesz napisać, aby wykorzystać te zaawansowane systemy. Rodzina interfejsów Google Data API stale się powiększa, udostępniając coraz więcej informacji, które możesz wykorzystywać w swoich aplikacjach. Platforma Salesforce.com oferuje wiele przydatnych narzędzi, które nie zostały omówione w tym artykule. Będę czekać na Twoje kolejne mashupy dla przedsiębiorstw w AppExchange.

Pozdrawiamy

Zasoby