Ticketing Connector
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Connects your application to ticketing platforms.

The Ticketing Connector connects your application to your customers' ticketing platforms. Synqly supports querying, creating, and updating tickets in the ticketing platforms.

Pagination

The Ticketing connector implements pagination using a cursor. Responses return a field cursor which can be included in the next GET request to retrieve the next page of results. If the cursor field is not included in the request, the first page of results will be returned.

The number of results returned is controlled with the limit query parameter. The default limit is 100.

Custom Fields

While many fields like Id, Name, Priority are standard fields, many providers support custom fields. Depending on the product, these fields can be per integration (for all projects covered by the integration), per project or per ticket. For Per ticket fields, that basically means that there is no global configuration on the provider end and each field can have different types of values for different tickets.

To use custom fields, one has to define the custom fields in the integration config. One can get and perform CRUD on custom field spec using the /v1/integrations api - GET, POST, PATCH and PUT. One would refer to the custom_field_mappings element in the config.

This configuration is a list

{
    "custom_field_mappings": [
        {
            "project_id": "*",
            "name": "due_date",
            "project_field_path": "Dates/due-date"
        },
        {
            "project_id": "TST",
            "name": "effort",
            "project_field_path": "effort"
        },
    ]
}

Here "*" means for all projects, and the second field is for "TST" project only. We do have project_field_path field but it is not used by all providers.

In addition, for some products, we can get remote field definitions via API. Please refer to ticketing API documentation for the details (API call /remote-fields)

Here is a table of custom field support in ticketing

Provider	Custom Fields Implemented?	Custom Field Scopes Supported	Remote field implemented?
Jira	Yes	Per Integration, Per Project	Yes
Mock	Yes	Per Integration, Per Project	No
PagerDuty	No
ServiceNow	Yes	Per Ticket	No
Torq	Yes	Per Ticket	No

Default project in configuration

For ServiceNow and Jira, in the integration configuration one can specify "default_project: XYZ". In the case of ServiceNow, this will map to a table that extends the incident table. If not specified, we will create tickets in the incident table. For Jira this refers to actual projects. If any api calls omit the project, then the default project for the integration, if specified, will be used. Search queries can use the project=XYZ filter to scope results.

Example Jira config with default project:

{
  "url": "https://acme.atlassian.net",
  "default_project": "My Project",
  "credential": {
    "type": "basic",
    "username": "user@acme.org",
    "secret": "redacted"
  }
}

Webhooks

Some ticketing providers can be configured to send events via webhooks. Currently only Jira and ServiceNow supports webhooks. Support for other ticketing providers is under development.

Configuring webhooks

Configuring an integration to use webhooks requires the following setup, some of which will be provider specific:

A webhook configuration must be added to the integration configuration, where you must specify one or more final destinations for the webhook events. Different events may be filtered to different URLs. For more information see the webhook_config field when configuring a provider.
The provider must be configured to post events to an integration specific webhook URL. To retreive this URL, use the List Integration WebHook Configurations operation using the Integration Token. This will return the unique URL for the Integration linked to the given Token.

Jira must be manually configured to use webhooks. If a signing key was used when configuring the webhook details in the provider configuration, this should be set along with the URL received from the above operation. See Jira Ticketing Provider Webhook Configuration Guide for more information.

ServiceNow can be automatically configured by using the Create Integration WebHook Configuration operation. A project must be specified. For ServiceNow this is usually the incident table.

Once you've configured the provider to send events to the Integration's unique webhook URL, you should start receiving webhook events at the destination(s) defined in the configuration.

Webhook Payload

The webhook payload that is sent to your webhook receiver will be as follows:

{
    "ticket_id":"TST-123",
    "entity_date":"20240930T122634.123+700",
    "priority": "MEDIUM",
    "short_description":"Test issue 123",
    "raw_payload": {
        ... raw payload
    }
}

The entity_date will be as specified in the webhook payload. Synqly does not modify the timestamp received from the provider. Fields that fit the Synqly common model are transformed; however, some fields do not fit our the common model depending on the provider. Such fields can be found in the raw_payload, which is always returned unchanged.

Webhook Security

Synqly will verify incoming payloads using the configured signing key, if one is specified and the provider supports signing the payload.

Synqly will always sign outgoing payloads. For more information including how to validate the signature, see our Webhook Signature Validation Guide

API Reference

For full API documentation see the Ticketing API Reference.

To create an integration with the Ticketing connector, use the Create Integration API endpoint, using one of the provider configs below.

Supported Providers

Atlassian Jira (ticketing_jira)
Autotask Operations Cloud (ticketing_autotask)
Freshdesk (ticketing_freshdesk)
Jira Service Management (ticketing_jira_service_management)
PagerDuty Operations Cloud (ticketing_pagerduty)
ServiceNow IT Service Management (ITSM) (ticketing_servicenow)
ServiceNow Security Incident Response (SIR) (ticketing_servicenow_sir)
Synqly Test Provider (ticketing_mock_ticketing)
Torq (ticketing_torq)
Zendesk (ticketing_zendesk)
[MOCK] PagerDuty Operations Cloud (ticketing_pagerduty_mock)

Supported Operators by Provider

API	Autotask Operations Cloud	Freshdesk	Atlassian Jira	Jira Service Management Configuration	Test Provider	PagerDuty Operations Cloud	[MOCK] PagerDuty Operations Cloud	ServiceNow ITSM	ServiceNow SIR	Torq	Zendesk
create_attachment	❌	❌	✅	✅	❌	❌	❌	❌	❌	❌	❌
delete_attachment	❌	❌	✅	✅	❌	❌	❌	❌	❌	❌	❌
download_attachment	❌	❌	✅	✅	❌	❌	❌	❌	❌	❌	❌
list_attachments_metadata	❌	❌	✅	✅	❌	❌	❌	❌	❌	❌	❌
create_comment	❌	❌	✅	✅	✅	✅	❌	✅	✅	✅	❌
delete_comment	❌	❌	✅	✅	✅	❌	❌	✅	✅	✅	❌
list_comments	❌	❌	✅	✅	✅	✅	✅	✅	✅	✅	❌
query_escalation_policies	❌	❌	❌	❌	❌	✅	✅	❌	❌	❌	❌
create_note	❌	❌	❌	❌	✅	❌	❌	✅	❌	✅	❌
delete_note	❌	❌	❌	❌	✅	❌	❌	✅	❌	✅	❌
patch_note	❌	❌	❌	❌	✅	❌	❌	❌	❌	✅	❌
list_notes	❌	❌	❌	❌	✅	❌	❌	✅	❌	✅	❌
list_on_call	❌	❌	❌	❌	❌	✅	✅	❌	❌	❌	❌
list_projects	❌	❌	✅	✅	✅	✅	✅	❌	❌	❌	❌
list_remote_fields	❌	❌	✅	✅	❌	❌	❌	✅	✅	❌	❌
create_ticket	✅	✅	✅	✅	✅	✅	❌	✅	✅	✅	✅
get_ticket	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
patch_ticket	✅	✅	✅	✅	✅	✅	❌	✅	✅	✅	✅
query_tickets	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅

APIs with Filters

API	Autotask Operations Cloud	Freshdesk	Atlassian Jira	Jira Service Management Configuration	Test Provider	PagerDuty Operations Cloud	[MOCK] PagerDuty Operations Cloud	ServiceNow ITSM	ServiceNow SIR	Torq	Zendesk
query_tickets	✅ [docs]	✅ [docs]	✅ [docs]	✅ [docs]	✅ [docs]	❌	❌	✅ [docs]	✅ [docs]	✅ [docs]	✅ [docs]

Ticketing ConnectorCopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude