Atividades de consulta do conector QuickBooks no Jitterbit Design Studio

Antes de poder consultar dados do QuickBooks a partir do Jitterbit, você precisará ter criado um endpoint do QuickBooks dentro do Jitterbit Studio (veja Conector QuickBooks OAuth 1.0a - criar endpoint ou Conector QuickBooks 2.0 - criar endpoint). Agora que o Jitterbit tem acesso à sua instância do QuickBooks Online, você pode realizar quatro atividades principais com seus dados do QuickBooks: Consultar, Criar, Atualizar ou Excluir.

Esta página foca na consulta de seus dados do QuickBooks, usando um exemplo de consulta de dados existentes do QuickBooks sobre um Cliente específico através de um arquivo XML pelo Jitterbit. Esses passos estão divididos em iniciar a atividade de consulta, definir os componentes da operação e implantar e executar a operação.

Criando uma operação de consulta QuickBooks

1. Dentro do seu projeto no Jitterbit Studio, existem várias maneiras de iniciar uma nova atividade de consulta QuickBooks. Cada uma das opções a seguir iniciará o Assistente de Consulta QuickBooks para guiá-lo pelo processo.

   • Vá para Arquivo > Novo > Conectores > Nova Consulta QuickBooks.
   • Na árvore à esquerda, sob Conectores, clique com o botão direito na categoria QuickBooks e selecione Nova Consulta QuickBooks.
   • Na árvore à esquerda, sob Conectores, clique duas vezes na categoria QuickBooks, depois clique com o botão direito em Atividades de Consulta QuickBooks e selecione Nova Consulta QuickBooks.
   • Na barra de ferramentas superior, clique no ícone do conector (peça de quebra-cabeça laranja) . Na janela pop-up, selecione QuickBooks e, em seguida, selecione Consulta QuickBooks.

2. A tela de Endpoint do Assistente de Consulta QuickBooks solicita que você selecione o endpoint do qual deseja consultar dados. Você já deve ter configurado endpoints em Conector QuickBooks OAuth 1.0a - criar endpoint ou Conector QuickBooks 2.0 - criar endpoint. Selecione o endpoint apropriado, por exemplo, um endpoint de sandbox ou de produção. Clique em Próximo quando terminar.

   Nota

   O exemplo usado nesta documentação consulta um conjunto de dados de amostra fornecido em cada nova sandbox QuickBooks. Para acessar sua sandbox, vá para https://developer.intuit.com/ e faça login na sua conta do QuickBooks Online. Uma vez logado, vá para Docs & Tools > Sandbox > Ir para empresa para a sandbox que você deseja usar. Dentro da sandbox, você verá os dados de amostra disponíveis para fins de teste.

   

3. A tela Objeto do Assistente de Consulta do QuickBooks pede que você selecione o Objeto do qual deseja consultar. Neste exemplo, usamos a API de Contabilidade durante a criação do aplicativo QuickBooks Online e, portanto, temos apenas um Objeto para selecionar: Contabilidade. Clique no Objeto e depois clique em Próximo para continuar.

   

4. A tela Componente do Assistente de Consulta do QuickBooks exibe todos os Componentes que estão disponíveis para consulta dentro da sua instância conectada do QuickBooks. Para os propósitos deste guia, vamos consultar um Cliente e, portanto, selecionar o componente Cliente. Em seguida, clique no botão Concluir.

   

5. O Jitterbit Studio irá prosseguir com a criação de uma estrutura de Solicitação e Resposta da API do QuickBooks que permitirá que os dados sejam consultados dentro da sua instância conectada do QuickBooks Online. Uma nova aba deve aparecer no Studio chamada Atividades de Consulta do QuickBooks. Você pode renomear sua consulta aqui, se desejar; no exemplo, a nossa é chamada "Consulta de Cliente do QuickBooks."

   Clique no ícone + à direita de ambas as visualizações da estrutura de Solicitação e Resposta para expandir todos os elementos dentro de cada estrutura. Com cada lado agora expandido, você deve ver uma tela semelhante à imagem mostrada abaixo.

   

6. Em seguida, na mesma tela, clique no botão Criar Operação localizado em Usar em uma Integração no canto superior direito. Isso criará a operação do Jitterbit que consultará o QuickBooks para dados de Cliente.

7. Uma nova aba deve abrir no Studio chamada Operações, contendo uma representação gráfica da atividade de Consulta. Salve sua Operação clicando no ícone de disco único para salvar apenas esta Operação ou no ícone de múltiplos discos para salvar todas as alterações no seu projeto de integração. Você deve ver o asterisco na aba Operações e o título da Operação desaparecer à medida que sua nova atividade de Consulta é criada e salva no seu projeto.

Definindo os componentes da operação

Agora precisamos definir os outros componentes da Operação que aparecem na representação gráfica, incluindo Fonte, Solicitação, Resposta e Destino. Para fins deste guia, fornecemos os seguintes exemplos para referência acima: Jitterpak QuickBooksExample.jpk e arquivos acompanhantes QuickBooksSampleRequestFiles.zip.

• Fonte (Opcional): No exemplo, o seguinte XML é uma solicitação de entrada para buscar um Cliente com o primeiro nome, ou NomeDado como é conhecido no QuickBooks, de 'Mark':

  CustomerQueryRequest.xml

  <ns:INPUT xmlns:ns="urn:qboln-res:document:qboln:oln:functions">
  <Customer>
  <Fields></Fields>
  <Condition>GivenName='Mark'</Condition>
  </Customer>
  </ns:INPUT>
  

  Nota

  No exemplo acima, os Campos estão vazios, o que buscará todos os campos para o Cliente. Se apenas certos campos forem necessários, use um delimitador "," (vírgula) entre os nomes dos campos (por exemplo, campo1,campo2,campo3). Em seguida, para aplicar Condições à consulta, especifique a cláusula desejada em Condições, como no exemplo abaixo.

  A partir da versão 8.25, o campo Condição também pode conter uma cláusula ORDERBY e/ou as palavras-chave STARTPOSITION e MAXRESULTS individualmente ou em combinação. Por exemplo:

  <Fields>Name,GivenName,FullyQualifiedName,AccountType</Fields> <Condition>GivenName='Mark' ORDERBY Name STARTPOSITION 0 MAXRESULTS 10</Condition>

  Para usar o arquivo XML, primeiro clique duas vezes no ícone da Fonte, em seguida, selecione um novo tipo de Fonte. Para este exemplo, estamos usando um agente privado com arquivos locais habilitados, e assim selecionamos um Tipo de "Arquivo Local" e depois Procurar para o local. Se você estiver usando os arquivos de exemplo e extraído para o local recomendado C:\, a Pasta é 'C:\projects\quickbooks' e o Obter Arquivos é 'CustomerQueryRequest.xml'.

  Nota

  Você pode optar por ignorar o uso de uma Fonte clicando com o botão direito no ícone da Fonte e selecionando Remover do Gráfico. Se você fizer isso, ao especificar a Solicitação, escolha uma Fonte de "Nenhuma" e, em vez disso, você pode clicar duas vezes nas variáveis do lado direito (lado do Destino) do mapeamento para especificar valores. Essas opções mais avançadas são abordadas em Transformações.

• Destino: Clique duas vezes no ícone do Destino. No exemplo, queremos gravar em um arquivo XML com a saída da consulta, então novamente selecionaremos um Tipo de "Arquivo Local" e Navegar até um local no agente privado onde queremos salvar os dados. No exemplo, a Pasta é 'C:\projects\quickbooks' e o Nome do Arquivo é 'CustomerQueryResponse.xml'.

• Solicitação: Clique duas vezes no ícone da Solicitação e selecione Criar Nova Transformação. Ou clique no botão Criar Solicitação na aba Atividades de Consulta do QuickBooks. Isso abrirá o Assistente de Transformação que o guiará na criação da Solicitação.

  1. Na primeira tela, Nome, selecione o tipo de Fonte usado acima. Para o exemplo, escolhemos XML. Deixe o Destino como padrão.
  2. Na próxima tela, Fonte, escolha o botão para Selecionar uma estrutura XML existente. No dropdown, selecione "Esquemas do QuickBooks." Em seguida, selecione 'QuickBooksQueryRequest.xsd' para usar como seu arquivo de estrutura. Na próxima tela, clique em Concluir.
  3. A aba Transformações deve abrir onde você pode completar seu mapeamento. Clique e arraste "Campos" do lado esquerdo (lado da Fonte) para "Campos" do lado direito (lado do Destino). Faça o mesmo com "Condição." Sua tela de mapeamento agora deve parecer semelhante à abaixo.

• Resposta: Clique duas vezes no ícone da Resposta e selecione Criar Nova Transformação. Ou clique no botão Criar Resposta na aba Atividades de Consulta do QuickBooks. Isso abrirá o Assistente de Transformação que o guiará na criação da Resposta.

  1. Na primeira tela, Nome, selecione o tipo de Destino usado acima. Para o exemplo, escolhemos XML. Deixe a Fonte como padrão.
  2. Na próxima tela, Fonte, escolha o botão para Selecionar uma estrutura XML existente. No dropdown, selecione "Esquemas do QuickBooks." Em seguida, selecione 'QuickBooksQueryResponse.xsd' para usar como seu arquivo de estrutura. Na próxima tela, clique em Concluir.
  3. A aba Transformações deve abrir onde você pode completar seu mapeamento. Clique no + na parte inferior de cada lado da Fonte e do Destino para expandir os itens em cada árvore. Clique e arraste a pasta "OUTPUT" do lado esquerdo (lado da Fonte) para a pasta "OUTPUT" do lado direito (lado do Destino). Sua tela de mapeamento agora deve parecer semelhante à abaixo.

Implantando e executando a operação

Com a atividade de Consulta do QuickBooks configurada, estamos prontos para implantar e executar a Operação.

Na aba de Operações, clique no ícone Implantar . Em seguida, clique no ícone Executar para colocar a Operação na fila para execução.

Na parte inferior da tela, o monitor de Operação deve indicar que sua Operação foi executada com sucesso. Se não, você pode clicar duas vezes no ícone de Status para visualizar quaisquer mensagens de log.

Você também deve ver agora a saída da consulta gerada no Destino que você especificou. No exemplo, o arquivo agora é criado em 'C:\projects\quickbooks\CustomerQueryResponse.xml':

title-"CustomerQueryResponse.xml" <ns:OUTPUT xmlns:ns="urn:qboln-res:document:qboln:oln:functions"> <ns:Customer> <ns:Id>17</ns:Id> <ns:SyncToken>0</ns:SyncToken> <ns:MetaData> <ns:CreateTime>2017-09-17T18:12:16-06:00</ns:CreateTime> <ns:LastUpdatedTime>2017-09-25T13:57:24-06:00</ns:LastUpdatedTime> </ns:MetaData> <ns:GivenName>Mark</ns:GivenName> <ns:FamilyName>Cho</ns:FamilyName> <ns:FullyQualifiedName>Mark Cho</ns:FullyQualifiedName> <ns:DisplayName>Mark Cho</ns:DisplayName> <ns:PrintOnCheckName>Mark Cho</ns:PrintOnCheckName> <ns:Active>1</ns:Active> <ns:PrimaryPhone> <ns:FreeFormNumber>(650) 554-1479</ns:FreeFormNumber> </ns:PrimaryPhone> <ns:PrimaryEmailAddr> <ns:Address>Mark@Cho.com</ns:Address> </ns:PrimaryEmailAddr> <ns:Taxable>0</ns:Taxable> <ns:BillAddr> <ns:Id>17</ns:Id> <ns:Line1>36 Willow Rd</ns:Line1> <ns:City>Menlo Park</ns:City> <ns:CountrySubDivisionCode>CA</ns:CountrySubDivisionCode> <ns:PostalCode>94304</ns:PostalCode> <ns:Lat>37.450412</ns:Lat> <ns:Long>-122.170593</ns:Long> </ns:BillAddr> <ns:ShipAddr> <ns:Id>17</ns:Id> <ns:Line1>36 Willow Rd</ns:Line1> <ns:City>Menlo Park</ns:City> <ns:CountrySubDivisionCode>CA</ns:CountrySubDivisionCode> <ns:PostalCode>94304</ns:PostalCode> <ns:Lat>37.450412</ns:Lat> <ns:Long>-122.170593</ns:Long> </ns:ShipAddr> <ns:Job>0</ns:Job> <ns:BillWithParent>0</ns:BillWithParent> <ns:Balance>314.28</ns:Balance> <ns:BalanceWithJobs>314.28</ns:BalanceWithJobs> <ns:CurrencyRef name="United States Dollar">USD</ns:CurrencyRef> <ns:PreferredDeliveryMethod>Print</ns:PreferredDeliveryMethod> </ns:Customer> </ns:OUTPUT>