Ticketing Connector

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

We have a ticketing webhooks implementation. This can be used to enable webhook workflows for specific providers.

Webhook receiver

Synqly will receive webhooks at /v1/hooks

The authentication header : "TOKEN: ACCESS_TOKEN" where ACCESS_TOKEN is the token for the integration, will have to be specified.

Supported Providers

Jira and Servicenow have been enabled for web hooks. Other ticketing providers are under development.

Webhook Configuration

Webhook configuration can be added to the integration config as follows:

{
    "items": [
        {
            "webhook_url": "https://final-recipient.com/my-hook",
            "event_filter": [
                "TicketCreated",
                "TicketDeleted"
            ]
        }
    ]
}

The field events_filter is optional, and if not specified, any event that comes in will be sent to the final recipient http://final-recipient.com/my-hook. In the above example, only Ticket Created and Deleted events will be forwarded to the configured final recipient. Currently the following events have been defined:

    TicketCreated
    TicketUpdated
    TicketDeleted
    TicketCommentCreated
    TicketCommentDeleted

The mapping of these events to specific events, e.g. TicketCreated in Jira is `jira:issue_created, is implemented in our system.

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

Support for signing incoming payloads for Synqly to validate, and for Synqly to sign payloads before sending out to configured outbound destinations is under development.

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)
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)

Supported Operators by Provider

API	Autotask Operations Cloud	Freshdesk	Atlassian Jira	Test Provider	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	Test Provider	PagerDuty Operations Cloud	ServiceNow ITSM	ServiceNow SIR	Torq	Zendesk
query_tickets	✅ [docs]	✅ [docs]	✅ [docs]	✅ [docs]	❌	✅ [docs]	✅ [docs]	✅ [docs]	✅ [docs]

Ticketing Connector

Pagination

Custom Fields

Default project in configuration

Webhooks

Webhook receiver

Supported Providers

Webhook Configuration

Webhook Payload

Webhook Security

API Reference

Supported Providers

Supported Operators by Provider

APIs with Filters

Was this helpful?