Fátima Miranda

Using Salesforce with Pentaho Data Integration

Pentaho Data Integration is the tool of the trade to move data between systems, and it doesn’t have to be just a business intelligence process. We can actually use it as an agile tool for point-to-point integration between systems. PDI has its own Salesforce input step which makes it a good candidate for integration.

What is Salesforce?

Salesforce is a cloud solution for customer relationship management (CRM). As a next generation multi-tenant Platform as a Service (PaaS), its unique infrastructure enables you to focus your efforts where they are most essential: creating microservices that can be leveraged in innovative applications and really speeding up the CRM development process.

Salesforce is the right platform to give you a complete 360º vision of your customer and his interactions with your brand, whether this happens via your email campaigns, call centres, social networks, or a simple phone call. Marketing automation is, for example, just one of the many great things Salesforce brings to you in an all-in-one platform.

How do we use PDI to connect to Salesforce?

For this access we need all our Salesforce connection details: the username, password and the SOAP web service URL. PDI has to be compatible with the SOAP API version that you use. For example:

  PDI version   SOAP API version number
  2.0   1.0
  3.8   20.0
  4.2   21.0
  6.0   24.0
  7.0   37.0
  8.2   40.0

 

Nevertheless, even if Salesforce gives us a new version of the API we can still use the old API perfectly well. Just be careful, because if you’ve created new modules inside the platform, the new API won’t have these customisations, and so you’ll need to use the Salesforce Object Query Language (SOQL) to get the data. But don’t worry, we’ll explain it all in the next section.

How do we use PDI to connect to Salesforce?

The SOQL syntax is quite similar to SQL syntax, but with a few differences:

  1. The SOQL does not recognise any special characters (such as * or ; ) and so we have to use all the fields that we will get from Salesforce, and we cannot add the ; at EOF.
  2. We cannot use comments in a query; SOQL does not recognise this either.
  3. To create joins we need to know a few things:
    • For the native modules that we need linkage to (direct relationship), we need to add in final name a ‘s’. For example:

Get all Orders with and without has Products (OrderItem Module)

  • For the customisation modules that we need to get data from another module (direct relationship) we need add to final name the  ‘__r’ . For example:
    Filter  OrderItems by Product_Skins__c field inside Product 2 Module 

How do we extract data from Salesforce with PDI?

We can use the Salesforce input step inside PDI to get data from Salesforce using SOQL; just be aware you can only use up to 20,000 characters to create the query.

  • Connection parameters specified:
    • Salesforce web service URL:

<url of Salesforce Platform>/services/Soap/u/<number of API Soap updated>

  • Username: Username Access to the Platform  (i.e. myname@pentaho.com)
  • Password:Password + Token (the company provides the token for us add to the password in Kettle.Properties) i.e: PASSWORDTOKEN

Settings parameters specified:

    • Specify query: Without active (like we can see in the image below) we only need to choose the module (the table containing records that we need to access).

For the next tab (Content) we have the following parameters options:

  • If we want to get all records from Salesforce (I mean, if we want to get delete records and insert records) you need place a tick in Query All Records, and choose from the parameters below one of the following options:
    • All (get new/update records and delete records), Update (get only inserts and update records) ;
    • If you untick the tick from Query All Records parameters, we only get insert/update registers;
    • Delete (we get only delete records).

How does PDI know if records are new/updates or deletes?

The Salesforce has native fields very useful for controlling the process. However we cannot see these fields in layout or on builder schema in SF. We only can see the data associated with these specific fields if we’re using the SOQL or PDI to access these fields.

  • CreatedById and CreateDate are fields that shows the user and data time when records were created.
  • The LastModifiedDate and LastModifiedID shows the data time and the user who modified the record. We can use these fields to get data updated in SF.
  • Id (Salesforce Id) present in URL as a string of 18 characters (Java config.) displays the register.
    For example:
  • We have more one native field IsDeleted with data type = Boolean that shows if the record was removed (IsDelete = true) or not (IsDelete = false).

In Additional field option we have three options:

  • Time out is useful in asynchrony systems because we can configure the timeout interval in milliseconds before the step times out;
  • Use Compression is useful to get more performance from the process. Because when you tick it, the system will direct all calls to the API and send all in .qzip field;
  • Limit is for configuring the maximum number of records to retrieve from the query.

Inside the last tab, we can see all fields from the query inside the first tab. Without SOQL we get all the module fields. With SOQL we get all the fields inside on SELECT function.

And for these cases, we need to do the manually changes.
For more details:

The base64 displays images or PDFs present in SF.

If we need send images (.jpeg) or pdf (.pdf) directly to SF we load these type of fields  using JAVA to convert binary files to the base64.

For example, to send a PDF file to SF:

How to load data to Salesforce with PDI?

Send data to Salesforce from other databases or from Salesforce.

The connection option is equal as described in Salesforce Input.
In Settings Options we have new parameters:

  • Rollback all Changes on error – if we got any error nothing will integrate into SF;
  • Batch Size – we can bring a static number of the records and integrate them simultaneously (the same batch) to SF;
  • In Output Fields Label we need to add the field name that we want to get the Salesforce ID for each record integrated.

In the Fields Option, we need to put field mapping.

  • For Module Field, we need to put the API Name field in SF to get the new data;
  • In the Steam Field, we need to put the name of the field that will be integrated into the respective field in SF;
  • Use External id = N to all field updated inside the respective Module;
  • Use External id = Y to all records that we need updating but are not present in the current module, but present in another module.

Delete records inside Salesforce

We delete records from Salesforce with Delete Salesforce step. We need to specify the key field from Table Input that does the reference to the key in Salesforce (Saleforce Id).

Update Salesforce records

If we only want to update records in SF we need to use the Salesforce Update Step.
Inside Fields (Key included) Option we need to add the key to records for the specific module.

Upsert data to Salesforce

If we want to insert and update in the same Batch to SF, we need to use Salesforce Upsert.
The parameter Upsert Comparison Field helps match the data in SF.

Fátima MirandaUsing Salesforce with Pentaho Data Integration
read more

Utilizar o Salesforce com Pentaho Data Integration

Pentaho Data Integration é a ferramenta mais indicada para mover dados entre diferentes sistemas, e não significa que seja necessariamente um processo de business intelligence. Pode ser utilizada como uma ferramenta ágil para integração ponto-a-ponto entre sistemas. O Pentaho Data Integration possui o seu próprio input step Salesforce, o que faz desta ferramenta uma opção fantástica em processos de integração.

O que é o Salesforce?

O Salesforce é uma solução em cloud para gestão de relacionamento com o cliente (CRM). Sendo uma Plataforma como Serviço (PaaS – Application as a Service) multi-tenant de última geração, a sua infraestrutura única permite-lhe focar todos os seus esforços nas áreas mais essenciais: criar micro-serviços com potencial de alavancagem em aplicações inovadoras e acelerar verdadeiramente o processo de desenvolvimento CRM.

O Salesforce é a plataforma ideal para lhe providenciar uma visão de 360º do seu cliente e das suas interações com a sua marca, independentemente de acontecerem via campanhas por e-mail, call centers, redes sociais ou uma simples chamada telefónica. A automação de marketing, por exemplo, é apenas uma das inúmeras vantagens que o Salesforce lhe oferece numa plataforma polivalente.

Como estabelecemos ligação entre o Pentaho Data Integration e Salesforce?

Para garantir o acesso, necessitamos de todos os detalhes de conexão do Salesforce: nome de utilizador, palavra-passe e o URL do serviço web SOAP. É imperativo que o PDI seja compatível com a versão da API SOAP que utiliza. Por exemplo:

  Versão do PDI   Versão da API SOAP
  2.0   1.0
  3.8   20.0
  4.2   21.0
  6.0   24.0
  7.0   37.0
  8.2   40.0

 

De qualquer forma, mesmo que o Salesforce nos providencie uma nova versão da API, ainda é possível utilizar a API anterior na perfeição. No entanto, tenha cuidado, porque caso tenha criado novos módulos na plataforma, a nova API não incluirá esses elementos personalizados e, consequentemente, terá que utilizar a linguagem Salesforce Object Query Language (SOQL) para obter os dados. Não se preocupe, pois explicaremos tudo na próxima secção.

Especificações SOQL

A sintaxe SOQL é bastante similar à sintaxe SQL, com algumas diferenças:

  1. O SOQL não reconhece quaisquer carateres especiais (tais como * ou ; ) e, portanto, é necessário utilizar todos os campos obtidos a partir do Salesforce, e não é possível adicionar o ; no EOF.
  2. Não é possível utilizar comentários em queries; o SOQL não os reconhece.
  3. Para criar joins necessitamos de saber algumas regras:
    • Em módulos nativos para os quais necessitamos de associações (relação direta), é necessário adicionar um ‘s’ ao nome final. Por exemplo:

Get all Orders with and without has Products (OrderItem Module)

    • Em módulos de personalização para os quais necessitamos de obter dados de outro módulo (relação direta) necessitamos de adicionar ‘__r’ ao nome final. Por exemplo:

Filter  OrderItems by Product_Skins__c field inside Product 2 Module

Como extraímos dados do Salesforce com o Pentaho Data Integration?

Podemos utilizar o input step Salesforce integrado no PDI para obter dados do Salesforce via SOQL; note que o limite máximo de carateres na criação de um query é de 20,000.

  • Parâmetros de conexão especificados:
    • Salesforce web service URL:

<url of Salesforce Platform>/services/Soap/u/<number of API Soap updated>

  • Nome de Utilizador: Nome de Utilizador de Acesso à Plataforma (ex.: myname@pentaho.com)
  • Palavra-passe:Palavra-passe + Token (a empresa providencia o token para adicionarmos à palavra-passe em Kettle.Properties) ex.: PASSWORDTOKEN
  • Definições especificadas:
    • Especificar o query: Sem ativo (como é possível verificar na imagem abaixo) necessitamos apenas de selecionar o módulo (a tabela que contem os registos aos quais pretendemos aceder).

Para o próximo separador (Content / Conteúdo) existem as seguintes opções:

  • Caso seja pretendido obter todos os registos do Salesforce (por outras palavras, obter registos “delete” e “insert” – “eliminados” e “inseridos”) é necessário assinalar a opção “Query All Records” e selecionar dos parâmetros abaixo uma das seguintes opções:
    • All (obter registos “new” (novos) e registos “delete” (eliminados)), Update (obter apenas “inserts” (inseridos) e registos “update” (atualizados));
    • Caso desmarque a opção “Query All Records” nos parâmetros, obteremos apenas registos “insert”/”update” – “inseridos”/”eliminados”;
    • Delete (obtemos apenas registos “delete” – “eliminados”).

De que forma o Pentaho Data Integration reconhece registos “novos” / “atualizados” ou “eliminados”?

O Salesforce possui campos nativos bastante úteis para controlar o processo. No entanto, não é possível observar esses campos no layout ou no esquema de construção em SF. Apenas os dados associados se encontram visíveis com estes campos específicos ao utilizar o SOQL ou PDI para aceder aos mesmos.

  • CreatedById e CreateDate são campos que exibem o utilizador, assim como a hora em que os registos foram criados.
  • LastModifiedDate e LastModifiedID mostra a hora e o utilizador que modificou o registo. Podemos utilizar estes campos para obter dados atualizados em SF.
  • Id (Salesforce Id), presente no URL como uma string de 18 carateres, (Java config.) exibe o registo.
    Por exemplo:
  • Temos um campo adicional, IsDeleted, com o tipo de dados = Boolean que informa se o registo foi removido (IsDelete = true) ou não (IsDelete = false).

No campo “Additional” / “Adicional”, temos três opções adicionais:

  • Time out é útil em sistemas assíncronos, uma vez que possibilita a configuração do intervalo “timeout” em milissegundos antes da expiração do step;
  • Use Compression é útil para obter mais performance do processo. Quando selecionada, esta opção fará com que o sistema redirecione todas as chamadas para a API e as envie em formato .qzip;
  • Limit serve para configurar o número máximo de registos a recolher do query.

No último separador é possível visualizar todos os campos do query no interior do primeiro separador. Sem o SOQL, obtemos todos os campos dos módulos. Com SOQL, obtemos todos os campos pertencentes à função SELECT.

Necessitamos de mais cuidado com a opção “Get Field Button”, uma vez que o Type (Tipo), Format (Formato) e Size (Tamanho) não podem ser corrigidos. Nestes casos, é necessário recorrer a alterações manuais.
Para obter mais detalhes:

O base64 exibe imagens ou PDFs presentes em SF.

Caso seja necessário enviar imagens (.jpeg) ou PDF (.pdf) diretamente para SF, carregamos este tipo de campos via JAVA, convertendo ficheiros binários para o base64.

Por exemplo, para enviar um ficheiro PDF para SF:

Como carregar dados para Salesforce via Pentaho Data Integration?

Envie dados para o Salesforce através de outras bases de dados ou a partir do Salesforce.

A opção de conexão é igual à descrita previamente no input Salesforce.
Nas opções das Definições (Settings), temos os seguintes parâmetros:

  • Rollback all Changes on error – caso nos deparemos com algum erro, nada será integrado em SF;
  • Batch Size – é possível trazer um número estático de registos e integrá-los simultaneamente (no mesmo batch) em SF;
  • Em Output Fields Label é necessário adicionar o nome do campo do qual pretendemos obter o Salesforce ID para cada registo integrado.

No parâmetro Fields Option, necessitamos de colocar o mapeamento dos campos.

  • Para Module Field, necessitamos de colocar o campo API Name em SF para obter novos dados;
  • Em Steam Field, é necessário colocar o nome do campo que será integrado no respetivo campo em SF;
  • Use External id = N para todos os campos atualizados no respetivo Módulo;
  • Use External id = Y para todos os registos que necessitamos atualizar, mas que não se encontram presentes noutro módulo.

Eliminar registos no Salesforce

Eliminamos registos do Salesforce com o step Delete Salesforce. É necessário especificar o campo chave do Table Input que faz a referência para a chave em Salesforce (Salesforce ID).

Atualizar registos Salesforce

Caso pretendamos apenas atualizar registos em SF, é necessário utilizar o Salesforce Update Step.
Incluído na seccção Fields (Key included) Option, necessitamos de adicionar a chave aos registos para o módulo específico.

Upsert de dados no Salesforce

Se desejarmos inserir e atualizar (“insert” e “update”) no mesmo Batch em SF, necessitamos de utilizar a funcionalidade Salesforce Upsert.
O parâmetro Upsert Comparison Field ajuda a comparar os dados em SF.

Fátima MirandaUtilizar o Salesforce com Pentaho Data Integration
read more