Channel framework startup tutorial - Step 7: Store state information in Zendesk Support (Metadata, Pull State)

Zendesk Support can store metadata and state for your integration, which allows you to build integrations without worrying about data storage, security, backup, etc. (Note: This doesn’t prevent you to add data storage to integration service if needed.)

There are two kinds of data an integration service needs:

  • Data about the integration account. For example, the WordPress service requires user login and WordPress location. Channel framework calls this the metadata.
  • Data that describes the current state of pulls. For example, timestamp of the last imported comment for the WordPress integration service. Channel Framework calls this the pull state.

Zendesk Support can store these two pieces of information. Zendesk Support provides them when it calls the integration service:

  • Pull calls and the admin UI will receive both the metadata and state
  • Channelback calls will receive the metadata Read the metadata and state documentation for more information on metadata and state.

Let’s review the code that handles this information.

In Step 5C , the integration service creates the metadata in this part of the response handler.

metadata = JSON.stringify({          name: attributes.name,          login: attributes.login,          password: attributes.password,          author: user.id,          wordpress_location: attributes.wordpress_location        });
        // Send the formatted data to Zendesk Support.  We do this by putting the info        // into a form and then programmatically submitting the form.        res.send(`<html><body> <form id="finish" method="post" action="${escapeString(attributes.return_url)}"> <input type="hidden" name="name" value="${escapeString(attributes.name)}"> <input type="hidden" name="metadata" value="${escapeString(metadata)}"> </form> <script type="text/javascript"> // Post the form var form = document.forms['finish']; form.submit(); </script> </body></html>`);

When the integration service receives a successful login for WordPress during setup, line 1-7 packages the metadata into a JSON string. Line 11-27 returns that to Zendesk Support using the return url.

In Step 2 , the code updates the state in the pull response handler:

newState = pullState(bodyInfo, state);

The pullState method is in wordpress.js:

function pullState(comments, previousState) {    if (!comments || !comments.length) {      return previousState || {};    }
    return {      most_recent_item_timestamp: comments[comments.length - 1].date_gmt    };  }

This method looks at the comments returned by WordPress. If there are any comments, the code extracts the timestamp of the most recent comment. The code puts that timestamp into the state.

The integration service returns state to Zendesk Support for every pull call, and receives the state back from Zendesk Support in the next pull call. The integration service uses state to decide what to query from WordPress. The code above demonstrated the integration can store state in Zendesk Support.

One thing to note - Zendesk Support never parses the metadata or state. This means that the integration service can use any format and any structure in these two fields, so long as it’s converted to a string. Both fields have length limit of 5000 characters.

Continue on Channel framework startup tutorial - Step 8: Provide native resource links in Zendesk Support (Clickthrough) .