Introduction

SiteDocs is used by thousands of customers worldwide. If you don’t know, it is a mobile-friendly, off-line capable app that allows users to complete and submit forms. Clients frequently use SiteDocs for on-site inspections and activities. Creating custom forms is easy and the forms can be electronically signed. The on-line nature of the documents improves compliance and awareness for information being tracked. SiteDocs can also keep track of certification for workers.

The SiteDocs customer base is currently in the thousands and is growing rapidly. One of our clients uses SiteDocs every day to capture information. Our client also uses SharePoint and wanted to get information captured in SiteDocs into SharePoint so that it can be incorporated into existing processes there.

The Challenges

SiteDocs has an API that allows authorized users to perform a long list of activities on the different entities defined by SiteDocs. Microsoft provides an API for SharePoint, plus, Power Automate can easily create and update SharePoint data. Power Automate creates flows that can be triggered by different events. A common trigger technique uses webhooks and API subscription to get notified of certain events as set up by the Power Automate user. The complexities of webhooks and event subscription is taken care of by services like Power Automate and Zapier.

Eureka iTech uses both these tools to automate processes for our customers. Microsoft and Zapier have connectors available to Software as a Service (SaaS) applications with APIs. There is some overlap as to what the SaaS applications Power Automate and Zapier support, but Zapier currently ties into more than 3,000 apps. Power Automate currently has connectors for around 600 apps and both companies are adding new ones constantly.

We wanted to keep our integration simple while staying within the Microsoft 365 environment. When Eureka was asked to investigate getting SiteDocs data into SharePoint, we found that Zapier has a connector for SiteDocs, but Power Automate does not. Both Zapier and Power Automate have connectors for generic HTTP requests however, which allow you to talk directly to an API to call functions that are not implemented by a connector. In the end, we set up a very simple zap in Zapier that was triggered by the SiteDocs event of a form being signed. The zap read the SiteDocs data from the trigger event and passed it to a Power Automate flow triggered by an HTTP request. All the processing of the SiteDocs data was then done in Power Automate.

The Solution

Working with the SiteDocs API did pose a few challenges. First, simply having a SiteDocs account doesn’t mean you get to use the API, as is the case for many other products. The API is an additional subscription. SiteDocs will generate an API authorization token for the user account that you will use to make calls to the SiteDocs API.

Once the token has been generated, you can use the Swagger powered API site to try each of the API functions. It is a quick way to confirm data is available and to see what format it is in. The API returns data using JSON, but some of the values in the JSON key-value pairs are actually more JSON that has been escaped to be passed as data and not more JSON objects. That was the second challenge, at least for me.

SiteDocs allows users to build forms with different types of input fields. One type of input field that is used frequently allows users to select from a list of predefined choices. In the form on the front end, it looks quite simple. For an example, look at Figure 1 below. The user filling out a form picks a value from a short list.

Figure 1: Simple choice field

However, when the API returns the content of the completed form, the data includes more than the field name and selected value. The JSON object for that field is shown in Figure 2.

Figure 2: JSON object for simple choice field

Most of the items in the object are simple key-value pairs, but the value for the Content and Value keys are escaped JSON objects that need to be unescaped. Furthermore, the Value object includes all the choices in the list. The selected choice needs to be identified by finding the attribute that has a value of true. For comparison, Figure 3 shows an example of a text field returned as JSON.

Figure 3: Simple text field JSON

The Parse JSON Action for Power Automate

In the Power Automate flow, we simply want to pull the field name and the value from the SiteDocs JSON. In a simple text field, that is easy enough. Just use a Parse JSON action, then grab the value of the Content key for the field name and the value of the Value key for the data the user entered.

If you look at the Content value in figure 2, you can see the first key value pair of the escaped JSON is “Label”: “LOA”. What needs to be done then in order to get the field name is showing in Figure 4 below. These steps are performed on each JSON object that represents a field from the SiteDocs form.

1. Parse the JSON object
2. Get the value of the Content key-value pair and assign it to a variable
3. Check to see if the value starts with a curly brace {
4. If no, then we should have a text string and don’t need to process it further
5. If yes, then the value is more JSON that needs to be parsed
6. From the parsed data, get the value of the Label key and update the variable

For this flow, we use variables to assign values to fields from SiteDocs. Later, we assign the variables to the values of the related fields in the SharePoint items we are creating or updated.

Figure 4: Power Automate actions to get field name

All that processing was required just to get the field name from SiteDocs. Now we need to get the value of the field. This will involve a similar technique of looking to see if the value starts with a burly brace or not. If it does, then it is JSON and will be parsed to get handle on the key-value pairs in the object. For a choice field, we need to perform additional processing.

Refer back to Figure 2 and look at the JSON again. The choices are the value for the Contents key and the value, once parsed, is an array as indicated by the beginning square brackets [ ]. To process the array, the Apply to each Power Automate action is used. For each object in the array, the object is parsed and the value of the selected key is check to see if it is true. If it is, then the value of the title key is assigned to a variable.

Figure 5: Getting the selected value from a choice field

Defining A Parse JSON Schema

We haven’t yet mentioned an important input for the Parse JSON action in Power Automate, the Schema.

Figure 6: The Power Automate Parse JSON action tile

The schema is a JSON object that describes the JSON that will be parsed. Power Automate will create the schema for you if you have a sample of the JSON that needs to be parsed. This easily done with the SiteDocs Swagger API page. Simply try the API method you will be calling in Power Automate, locate and copy to the clipboard the JSON object that you need to parse. Next, on the Parse JSON action step click Generate from sample and paste the JSON into the dialog box titled Insert a sample JSON Payload that opens when you.

Figure 7: Insert a sample JSON Payload dialog box

The schema for the data you pasted is automatically added to the Parse JSON action when you click the Done button and confirm you want the schema updated.

The Results

This blog post is has covered how we resolved some of the technical challenges of integrating SiteDocs with SharePoint. In our next post, we will elaborate on how this effort resulted in another success story for our clients. Many systems, like SiteDocs and SharePoint provide great value to the organization that use them. When you can combine them, the value is multiplied and the return on IT investments is increased.

Contact us today to discuss how we can help your organization get more from their information technology investments.