Actividades de consulta del conector de QuickBooks en Jitterbit Design Studio

Antes de poder consultar datos de QuickBooks desde Jitterbit, necesitará haber creado un endpoint de QuickBooks dentro de Jitterbit Studio (consulte Conector de QuickBooks OAuth 1.0a - crear endpoint o Conector de QuickBooks 2.0 - crear endpoint). Ahora que Jitterbit tiene acceso a su instancia de QuickBooks Online, puede realizar cuatro actividades principales con sus datos de QuickBooks: Consultar, Crear, Actualizar o Eliminar.

Esta página se centra en consultar sus datos de QuickBooks, utilizando un ejemplo de consulta de datos existentes de QuickBooks sobre un Cliente específico a través de un archivo XML mediante Jitterbit. Estos pasos se dividen en el inicio de la actividad de consulta, la definición de los componentes de operación y la implementación y ejecución de la operación.

Creando una operación de consulta de QuickBooks

1. Dentro de tu proyecto en Jitterbit Studio, hay varias formas de comenzar una nueva actividad de consulta de QuickBooks. Cada una de las siguientes opciones iniciará el Asistente de consulta de QuickBooks para guiarte a través del proceso.

   • Ve a Archivo > Nuevo > Conectores > Nueva consulta de QuickBooks.
   • En el árbol a la izquierda bajo Conectores, haz clic derecho en la categoría QuickBooks, luego selecciona Nueva consulta de QuickBooks.
   • En el árbol a la izquierda bajo Conectores, haz doble clic en la categoría QuickBooks, luego haz clic derecho en Actividades de consulta de QuickBooks y selecciona Nueva consulta de QuickBooks.
   • En la barra de herramientas superior, haz clic en el ícono del conector (pieza de rompecabezas naranja) . En el popup, selecciona QuickBooks, luego selecciona Consulta de QuickBooks.

2. La pantalla de Endpoint del Asistente de consulta de QuickBooks te pide que selecciones el endpoint del cual deseas consultar datos. Ya deberías haber configurado endpoints en Conector de QuickBooks OAuth 1.0a - crear endpoint o Conector de QuickBooks 2.0 - crear endpoint. Selecciona el endpoint apropiado, por ejemplo, un endpoint de sandbox o de producción. Haz clic en Siguiente cuando termines.

   Nota

   El ejemplo utilizado en esta documentación consulta un conjunto de datos de muestra proporcionados en cada nuevo sandbox de QuickBooks. Para acceder a tu sandbox, ve a https://developer.intuit.com/ e inicia sesión en tu cuenta de QuickBooks Online. Una vez que hayas iniciado sesión, ve a Docs & Tools > Sandbox > Ir a la empresa para el sandbox que deseas usar. Dentro del sandbox verás los datos de muestra disponibles para fines de prueba.

   

3. La pantalla de Objeto del Asistente de Consulta de QuickBooks te pide que selecciones el Objeto del cual te gustaría consultar. En este ejemplo, utilizamos la API de Contabilidad durante la creación de la aplicación de QuickBooks Online y, por lo tanto, solo tenemos un Objeto para seleccionar: Contabilidad. Haz clic en el Objeto y luego haz clic en Siguiente para continuar.

   

4. La pantalla de Componente del Asistente de Consulta de QuickBooks muestra todos los Componentes que están disponibles para ser consultados dentro de tu instancia de QuickBooks conectada. Para los propósitos de esta guía, consultaremos un Cliente y, por lo tanto, seleccionaremos el componente Cliente. Luego haz clic en el botón Finalizar.

   

5. Jitterbit Studio procederá a crear una estructura de Solicitud y Respuesta de la API de QuickBooks que permitirá consultar datos dentro de tu instancia de QuickBooks Online conectada. Debería aparecer una nueva pestaña en Studio llamada Actividades de Consulta de QuickBooks. Puedes renombrar tu consulta aquí si lo deseas; en el ejemplo, la nuestra se llama "Consulta de Cliente de QuickBooks."

   Haz clic en el ícono + en el extremo derecho de las vistas de estructura de Solicitud y Respuesta para expandir todos los elementos dentro de cada estructura. Con cada lado ahora expandido, deberías ver una pantalla que es similar a la imagen mostrada a continuación.

   

6. A continuación, en la misma pantalla, haz clic en el botón Crear Operación ubicado bajo Usar en una Integración en la esquina superior derecha. Esto creará la operación de Jitterbit que consultará a QuickBooks por datos de Cliente.

7. Debería abrirse una nueva pestaña en Studio llamada Operaciones, que contiene una representación gráfica de la actividad de Consulta. Guarda tu Operación haciendo clic en el ícono de disco simple para guardar solo esta Operación o en el ícono de discos múltiples para guardar todos los cambios en tu proyecto de integración. Deberías ver que el asterisco en la pestaña de Operaciones y el título de la Operación desaparecen a medida que tu nueva actividad de Consulta se crea y guarda en tu proyecto.

Definiendo los componentes de la operación

Ahora necesitamos definir los otros componentes de la Operación que aparecen dentro de la representación gráfica, incluyendo Fuente, Solicitud, Respuesta y Destino. Para los propósitos de esta guía, proporcionamos los siguientes ejemplos para referencia: Jitterpak QuickBooksExample.jpk y archivos acompañantes QuickBooksSampleRequestFiles.zip.

• Fuente (Opcional): En el ejemplo, el siguiente XML es una solicitud de entrada para obtener un Cliente con el primer nombre, o GivenName como se conoce en 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

  En el ejemplo anterior, los Campos se dejan vacíos, lo que obtendrá todos los campos para el Cliente. Si solo se necesitan ciertos campos, use un delimitador "," (coma) entre los nombres de los campos (por ejemplo, field1,field2,field3). Luego, para aplicar Condiciones a la consulta, especifique la cláusula deseada en Condiciones como en el ejemplo a continuación.

  A partir de la versión 8.25, el campo de Condición también puede contener una cláusula ORDERBY, y/o las palabras clave STARTPOSITION y MAXRESULTS individualmente o en combinación. Por ejemplo:

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

  Para usar el archivo XML, primero haga doble clic en el ícono de Fuente, luego seleccione un nuevo tipo de Fuente. Para este ejemplo, estamos utilizando un agente privado con archivos locales habilitados, y por lo tanto seleccionamos un Tipo de "Archivo Local" y luego Examinar para la ubicación. Si está utilizando los archivos de ejemplo y los extrajo a la ubicación recomendada C:\, la Carpeta es 'C:\projects\quickbooks' y el Obtener Archivos es 'CustomerQueryRequest.xml'.

  Nota

  Puedes optar por omitir el uso de una Fuente haciendo clic derecho en el ícono de la Fuente y seleccionando Eliminar del Gráfico. Si haces esto, al especificar la Solicitud, elige una Fuente de "Ninguna" y en su lugar puedes hacer doble clic en las variables del lado derecho (lado del Destino) del mapeo para especificar valores. Estas opciones más avanzadas se cubren en Transformaciones.

• Destino: Haz doble clic en el ícono de Destino. En el ejemplo, queremos escribir en un archivo XML con la salida de la consulta, así que nuevamente seleccionaremos un Tipo de "Archivo Local" y Examinar para una ubicación en el agente privado donde queremos guardar los datos. En el ejemplo, la Carpeta es 'C:\projects\quickbooks' y el Nombre de Archivo es 'CustomerQueryResponse.xml'.

• Solicitud: Haz doble clic en el ícono de Solicitud y selecciona Crear Nueva Transformación. O haz clic en el botón Crear Solicitud en la pestaña Actividades de Consulta de QuickBooks. Esto abrirá el Asistente de Transformación que te guiará a través de la creación de la Solicitud.

  1. En la primera pantalla, Nombre, selecciona el tipo de Fuente utilizado arriba. Para el ejemplo elegimos XML. Deja el Destino como predeterminado.
  2. En la siguiente pantalla, Fuente, elige el botón para Seleccionar una estructura XML existente. En el menú desplegable selecciona "Esquemas de QuickBooks." Luego selecciona 'QuickBooksQueryRequest.xsd' para usar como tu archivo de estructura. En la siguiente pantalla, haz clic en Finalizar.
  3. La pestaña de Transformaciones debería abrirse donde puedes completar tu mapeo. Haz clic y arrastra "Campos" desde el lado izquierdo (lado de la Fuente) a "Campos" en el lado derecho (lado del Destino). Haz lo mismo con "Condición." Tu pantalla de mapeo ahora debería verse similar a la de abajo.

• Respuesta: Haz doble clic en el ícono de Respuesta y selecciona Crear Nueva Transformación. O haz clic en el botón Crear Respuesta en la pestaña Actividades de Consulta de QuickBooks. Esto abrirá el Asistente de Transformación que te guiará a través de la creación de la Respuesta.

  1. En la primera pantalla, Nombre, selecciona el tipo de Destino utilizado arriba. Para el ejemplo elegimos XML. Deja la Fuente como predeterminada.
  2. En la siguiente pantalla, Fuente, elige el botón para Seleccionar una estructura XML existente. En el menú desplegable selecciona "Esquemas de QuickBooks." Luego selecciona 'QuickBooksQueryResponse.xsd' para usar como tu archivo de estructura. En la siguiente pantalla, haz clic en Finalizar.
  3. La pestaña de Transformaciones debería abrirse donde puedes completar tu mapeo. Haz clic en el + en la parte inferior de cada lado de la Fuente y el lado del Destino para expandir los elementos en cada árbol. Haz clic y arrastra la carpeta "OUTPUT" desde el lado izquierdo (lado de la Fuente) a la carpeta "OUTPUT" en el lado derecho (lado del Destino). Tu pantalla de mapeo ahora debería verse similar a la de abajo.

Desplegando y ejecutando la operación

Con la actividad de Consulta de QuickBooks configurada, estamos listos para desplegar y ejecutar la operación.

Desde la pestaña de Operaciones, haz clic en el icono de Desplegar . Luego haz clic en el icono de Ejecutar para colocar la operación en la cola para su ejecución.

En la parte inferior de la pantalla, el monitor de Operaciones debería indicar que su Operación se ejecutó con éxito. Si no, puede hacer doble clic en el ícono de Estado para ver cualquier mensaje de registro.

También debería ver ahora la salida de la consulta generada en el Destino que especificó. Para el ejemplo, el archivo ahora se crea en '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>