Iterators for Call URL actions and Webhooks

As you know, Call URL actions and Webhooks serve to implement integrations with third-party systems in TeamDesk. Both are extremely effective for data exchange and both have one limitation – inability to easily process multiple data items. This is what we have addressed today with iterators.

Let’s take Xero accounting software as an example.

When something changes in Xero it sends the event to your webhook, listing what was changed, type of change and identifier of the changed resource. Typical JSON payload it sends looks like this:

{
  "events": [
    {
      "resourceUrl": "https://api.xero.com/api.xro/2.0/Invoices/01234567-0123-4567-8901-012345678901",
      "resourceId": "01234567-0123-4567-8901-012345678901",
      "eventDateUtc": "2021-01-01T00:00:00.000",
      "eventType": "UPDATE",
      "eventCategory": "INVOICE",
      "tenantId": "01234567-0123-4567-8901-012345678901",
      "tenantType": "ORGANISATION"
    }
  ],
  "firstEventSequence": 1,
  "lastEventSequence": 1,
  "entropy": "ABCDEFGHIJKLMNOPQRST"
}

In your webhook you should normally have:

A column to store either resource ID or URL
An assignment to that column, like this: Response("$.events[0].resourceUrl")
A change trigger that works when record is created
And a Call URL action that gets full resource information based on stored resource ID/URL.

But you might have noticed “events” field is decorated as array (or list if you prefer). For the most part you’ll have the only item in the list, but depending on change rate or Xero load it may pack multiple events together. And Xero is not unique, there are many other APIs that pack events together to reduce server load.

With multiple events packed together you’ll get the sort of:

{
  "events": [
    {
      "resourceUrl": "https://api.xero.com/api.xro/2.0/Invoices/01234567-0123-4567-8901-012345678901",
      "resourceId": "01234567-0123-4567-8901-012345678901",
      "eventDateUtc": "2021-01-01T00:00:00.000",
      "eventType": "UPDATE",
      "eventCategory": "INVOICE",
      "tenantId": "01234567-0123-4567-8901-012345678901",
      "tenantType": "ORGANISATION"
    }, 
    {
      "resourceUrl": "https://api.xero.com/api.xro/2.0/Invoices/98765432-3210-3210-3210-109876543210",
      "resourceId": "98765432-3210-3210-3210-109876543210",
      "eventDateUtc": "2021-01-01T00:00:01.000",
      "eventType": "UPDATE",
      "eventCategory": "INVOICE",
      "tenantId": "01234567-0123-4567-8901-012345678901",
      "tenantType": "ORGANISATION"
    }
  ],
  "firstEventSequence": 1,
  "lastEventSequence": 1,
  "entropy": "ABCDEFGHIJKLMNOPQRST"
}

Our webhooks use “one request creates one record” model, so if you are going to handle multiple events you’ll have to duplicate the logic: another storage column and assignment and trigger and action for each event. But real problem is that you do not know how many items might be in the list — any number you are going to handle might not be enough.

But now we have iterators to help!

Iterators in Webhooks

Iterators allow you to select repeating entries from JSON or XML payload and create a record in some table for each selected entry.

In Xero case first you should declare you are going to iterate over the “events” fields. First, we’ll create “Xero Events” table and set up all the logic described above (column, trigger, action) there.

Now to iterator setup. Let’s check incoming data and click on an value (“resourceUrl” field) we are interested in:

Iterator's path and assignment expression

You’ll see two new boxes we display for the content that might be iterated. Let’s copy the values. Now, let’s go back to webhook setup. There is also new Iterators section:

Let’s create new iterator and paste the expression from the top box there.

Save, and create new assignment. The end result will look as:

Voilà! We are capable to handle any arbitrary number of the events in Xero webhook! We will process each event uniformly and there is no need to duplicate the logic.

Iterators in Call URL actions

As Xero reports Invoice information together with line items we can use iterators to copy all invoice data in one shot. Xero’s invoice information is quite long, here is excerpt with some essential info:

<Response>
  <Invoices>
    <Invoice>
      <InvoiceID>01234567-0123-4567-8901-012345678901</InvoiceID>
      <Date>2021-01-01T00:00:00</Date>
      <Contact>
        <Name>John Doe</Name>
      </Contact>
      <LineItems>
        <LineItem>
          <LineItemID>01234567-0123-4567-8901-012345678901</LineItemID>
          <Description>Acme Wild-Cat</Description>
          <UnitAmount>100.00</UnitAmount>
          <Quantity>2.0000</Quantity>
        </LineItem>
        <LineItem>
          <LineItemID>98765432-3210-3210-3210-109876543210</LineItemID>
          <Description>Weyland-Yutani Xenomorph</Description>
          <UnitAmount>200.00</UnitAmount>
          <Quantity>1.0000</Quantity>
        </LineItem>
      </LineItems>
    </Invoice>
  </Invoices>
</Response>

Iterators in Call URL actions are organized the same way as in webhooks, so we won’t repeat step-by-step guide from above, just the final result: