Installation guide for the API Data Sync app

Watch the installation video (written step-by-step guide below):

1. Install the app

1. Click this link to open the app in the Zendesk Marketplace.
2. Click the Install button on the right.
3. Select the Zendesk instance where you want to install the app.
4. Follow the redirection to your Zendesk Admin space. (Make sure you have admin rights.)
5. (Optional) Rename the app (default: "API Data Sync by Knots") or set role/group restrictions as needed.
6. Click Install to finish the setup.

2. Access the app

1. Open your Agent Workspace:
   • Click the four-square icon at the top-right, then select Support.
2. In the Support Workspace, find the API Data Sync by Knots app icon on the left panel.
   • If it's not visible, click the three dots at the bottom left to locate hidden apps.
     

3. Log in or create a Knots account

On the Settings page, click Login to either:

• Create a new Knots account.
• Log in if you already have a Knots account.
  

4. Set up the connector to sync data via API

Before creating a new trigger, you need to set up a connector to pull in data. 

1. Click + New trigger.
2. Click Setup connector. This will take you to the Knots.io connectors console.
                                          
3. Choose a connector type that fits your use case. You can either:
   • Use a predefined connector for supported systems (e.g. Azure, SharePoint, etc.), or
   • Create a generic connector using Basic Auth, API key, Oauth, or other authentication methods.
4. Fill in the necessary connection details. For a walkthrough of the most common setups, see our connector setup guide.
5. Click Setup connector to save your configuration.
                
6. Go back to Zendesk and click Refresh in the app to load your new connector. It will now appear in the connectors list. 
                                         

5. Set up the trigger

Trigger Section:

1. Name your trigger – something clear and recognizable.
2. Add a tag – this ensures the trigger runs only once per ticket, preventing trigger loops.

API Section: 

1. Choose what kind of data you want to fetch and define the Load Type:
   • Get API Data: Pulls in data from an external service.
   • Get Followup Ticket Data: Uses info from an older ticket in a follow-up ticket.
2. Fill out the Relative URL path to the service (required field). This path gets added to the connector’s base URL. You can use Zendesk placeholders to make it dynamic.

   

3. Pick the HTTP request method based on your integration needs:
   • GET: Request data from a server but do not modify it.
   • POST: Send data to the server, creating a new resource.
   • PUT: Update an existing resource or create it if it does not exist.
   • DELETE: Remove the specified resource from the server.
   • PATCH: Partially update an existing resource with the provided data
4. (Optional) Add HTTP headers for authentication and integration-specific needs

Parse Results Section: Define how the response data should be mapped:  

1. Enter the Path to the source property in result object (e.g., data.user.email), which is the path to the specific id that should be parsed/added to the ticket.
   • Choose what part of the response you need
   • Not sure how to fill it out? Click the link to the JSON Pathfinder to find the correct path. There, paste the response payload into the tool. Select the required attributes, copy the generated path, and paste it back here (remove the x from the beginning).

     

2. Choose where to store the data in Zendesk by picking one of the options in the Destination field to store value. This can be any ticket field, including private and public comments.

   

3. (Optional) Configure Response value mapping to map possible values from the source field to Zendesk field options.
4. (Optional) Configure Value conditions if you want to trigger actions based on numerical values:
   • Click + Add value conditions

   • Set conditions Operator to compare source value (e.g., >, <, =), Min value (e.g., 10 for stock quantity), and Add a tag when conditions are met Example:

     If the API response contains a field stock_quantity, you can set the condition where >0 adds the "in_stock" tag.

     

5. Save the trigger
   • Click Save and Activate to finish.
     You can now manage this trigger in the Zendesk Admin center to configure additional trigger conditions and further restrict or allow actions based on business needs. 

6. Test the configuration

1. Create a test ticket in Zendesk.
2. Observe the app's behavior:
   • The trigger should retrieve the specified data.
   • The response should be stored in the ticket field that you selected in the Destination Field to Store Value.
3. Review the trigger details:
   • Check the category, conditions, and payload structure.
   • Modify restrictions as needed to refine execution.

7. Make final adjustments

1. Ensure all settings align with your business requirements.
2. Adjust trigger conditions or tags for efficiency.
3. If necessary, refine data retrieval paths and connector settings.

Troubleshooting Tips

• If the app does not appear after installation, refresh the Zendesk Agent Workspace.
• If data is not being retrieved:
  • Check your connector authentication settings.
  • Verify the webhook URL or endpoint.
  • Review the trigger conditions and restrictions.
  • Use JSON Pathfinder to check if you're using the correct data path.
  • Ensure the relative URL path is correct.

For more information about the app, visit API Data Sync for Zendesk.

If you have any questions or suggestions regarding this app, please reach out to us at support@knots.io or through our contact form.