SysAid AirSync Connector

The SysAid connector imports tickets, users, companies, groups, assets, knowledge base articles, service catalog templates, and CMDB classifications into DevRev. It supports both initial full synchronization and incremental updates, so your DevRev data stays current without re-ingesting records that have not changed.

What This Connector Does

• Imports service requests from SysAid with full field coverage (title, description, status, priority, category, sub-category, requester, assignee, company, and assigned group)

• Syncs users including administrators, with an is_administrator flag instead of duplicate admin accounts

• Captures company records with their location and contact details

• Brings in groups and memberships so tickets land with the correct group ownership

• Imports hardware assets with owner, company, manufacturer, serial number, and operational fields

• Syncs knowledge base articles with author attribution resolved against your SysAid user list

• Imports service catalog templates offered in the SysAid self-service portal

• Captures the CMDB backbone — configuration item types, subtypes, and relation type definitions

• Supports incremental sync to minimize API calls and stay efficient between runs

Entities Synced

The connector extracts the following entity types from SysAid:

Core ITSM Entities

Service Requests Incremental Filter: The connector uses SysAid's update_time> query parameter on /api/v1/sr to fetch only tickets modified since the previous successful sync. On the first run this returns the full ticket history.

User Deduplication: SysAid exposes administrators inside the regular /users endpoint. The connector brings them across as normal user records with is_administrator = true. There are no duplicate "admin" objects.

Groups and Membership

Group Description Fallback: If a SysAid group has no description, the connector uses the group type (for example, administrators or general) as the description so downstream systems always see non-empty content.

Asset Management

Assets Incremental Filter: SysAid's Connect API /assets endpoint does not accept a "modified since" parameter, but every asset in the response carries an updateTime. On incremental runs the connector fetches the list, then pushes only assets whose updateTime is strictly after the previous sync timestamp. The sync log reports Fetched N, pushed M (filtered out K unchanged) so you can see the savings.

Knowledge Base and Service Catalog

Article Incremental Filter: Same strategy as assets — the connector reads updateTime (falling back to createdOn) and pushes only changed articles on incremental runs.

Article Authorship: Authors are resolved by matching the SysAid username field against your imported user list. A user who exists in SysAid shows up as a linked DevRev user on their articles. If the author is not in your imported user list, the raw SysAid username is kept as a text field.

CMDB Reference Data

Incremental Sync Summary

For entities without a "modified since" mechanism, the connector always performs a full fetch but DevRev de-duplicates by the stable SysAid ID, so you never see duplicate records.

Prerequisites

Before installing the connector, ensure you have:

1. SysAid Administrator Account: You need a SysAid administrator username and password. A standard end-user account does not have API access.

2. DevRev Account: An active DevRev organization with AirSync enabled.

3. DevRev Admin Role Permissions:

   • Grant full privileges for all custom objects in DevRev, including subtypes.

   • Navigate to Settings → Roles & Permissions → Admin Role.

   • Enable read, write, and manage permissions for all custom object types that will store SysAid data.

   • This ensures the connector can create and update records for companies, user details, assets, service catalog items, and CMDB entities.

4. SysAid Subdomain: The part of your SysAid URL before .sysaidit.com. For example, if you log in at https://acme.sysaidit.com, your subdomain is acme.

5. API Access: The SysAid administrator account must have read access to:

   • Service Requests

   • Users

   • Companies

   • Groups and Group Members

   • Assets

   • Knowledge Base (FAQ)

   • Templates (Service Catalog)

   • CMDB types

Installation

Step 1: Configure DevRev Permissions

Before connecting to SysAid, ensure your DevRev admin role has the necessary permissions:

1. Log in to your DevRev account as an administrator.

2. Navigate to Settings → Roles & Permissions.

3. Select the Admin Role (or the role that will manage the connector).

4. Scroll to the Custom Objects section.

5. Enable full privileges (Create, Read, Update, Delete) for:

   • All custom object types

   • All subtypes within each custom object

6. This ensures the connector can properly sync and map SysAid entities to DevRev records.

7. Click Save Changes.

Important: Without these permissions, the connector may fail to create or update records in DevRev, resulting in sync errors or incomplete data.

Step 2: Prepare a SysAid Service Account

1. Log in to your SysAid Administrator Portal.

2. Navigate to Tools → User Management → Administrators.

3. Create a new administrator account (or identify an existing one) dedicated to the DevRev sync.

4. Assign the account an administrator role with read access to the entities listed above.

5. Note the username and password — you will use them in the next step.

Tip: Use a dedicated service account, not a personal account. Password resets and role changes on a personal account break the sync.

Step 3: Install the Connector in DevRev

1. Log in to your DevRev account.

2. Navigate to Settings → Integrations.

3. Search for SysAid in the connector marketplace.

4. Click Install on the SysAid AirSync connector.

5. The connector is now added to your DevRev organization.

Step 4: Configure a Connection

1. After installation, click Configure on the SysAid connector.

2. Click Add Connection to create a new SysAid connection.

3. Provide the following information:

   • Connection Name: A friendly name for this connection (e.g., "SysAid Production").

   • SysAid Subdomain: Your SysAid organization subdomain (e.g., if your SysAid URL is https://acme.sysaidit.com, enter acme).

   • Username: The SysAid administrator username from Step 2.

   • Password: The password for that account.

4. Click Test Connection to verify the credentials. DevRev verifies by calling the SysAid login endpoint.

5. If the test succeeds, click Save.

Step 5: Review the Configuration

1. After saving the connection, review the default sync settings.

2. Decide whether to trigger the first sync immediately or schedule it for off-peak hours.

3. Click Save Configuration.

Running a Sync

Initial Sync

The first sync performs a full import of all entities:

1. Navigate to the SysAid connector configuration.

2. Click Run Sync.

3. The connector fetches all users, companies, groups, tickets, assets, knowledge articles, templates, and CMDB reference data.

4. Depending on your SysAid organization size, the initial sync can take several minutes to several hours.

5. You can monitor progress in the Sync History tab.

Note: The initial sync fetches every ticket in SysAid. For tenants with a very large ticket history, the first sync may take longer than subsequent runs.

Incremental Sync

After the initial sync, subsequent syncs fetch only changes:

1. Schedule automatic syncs or trigger them manually.

2. The connector uses the last successful sync timestamp as the incremental watermark.

3. Incremental syncs are significantly faster and use fewer API calls.

On incremental runs, the sync log reports exactly how many records were fetched and how many were pushed into DevRev. For assets and KB articles this looks like:

[extractAssets] Fetched 20, pushed 1 (filtered out 19 unchanged)

Sync Frequency Recommendations

• Hourly: For organizations requiring near-real-time ticket visibility in DevRev.

• Daily: For most organizations (recommended).

• Weekly: For small organizations with infrequent ticket changes.

Consider your SysAid API rate limits when setting sync frequency. The connector automatically handles rate limiting by pausing and retrying when limits are reached.

Configuration Options

All tunable values live in the connector's runtime settings. Sensible defaults ship with the snap-in; you can override via environment variables when deploying or running locally.

Authentication

The connector uses admin username and password authentication. DevRev stores the credentials in its keyring service and never displays the password in logs or in the UI after configuration.

Credential Storage

• Credentials are stored securely in DevRev's keyring service.

• Credentials are encrypted at rest and in transit.

• The password value is never logged or displayed in the UI after initial configuration.

• The structured logger redacts any context field whose name matches password, secret, token, api_key, authorization, or cookie before writing.

Token Verification

When you save a connection, DevRev verifies the credentials by calling:

POST https://{subdomain}.sysaidit.com/api/v1/login

If the login succeeds, the credentials are valid and the account has sufficient access.

Rotation

Rotate credentials following your organization's security policies:

1. Update the password in SysAid.

2. Update the connection in DevRev (Settings → Integrations → SysAid → Edit Connection).

3. Click Test Connection to confirm the new credentials work.

4. Save.

Error Handling and Resilience

The connector is designed to handle transient errors gracefully.

Rate Limiting (HTTP 429)

When SysAid rate limits are reached:

1. The connector reads the retry-after header to determine the wait time.

2. The sync pauses automatically and resumes after the rate limit resets.

3. No data is lost or skipped during the pause.

Tip: If you encounter frequent rate limiting, reduce your sync frequency.

Permission Errors (HTTP 403 / 405)

If the service account lacks permissions for a specific endpoint:

1. The connector skips that entity type with a warning.

2. Other entity types continue to sync normally.

3. The sync completes with a summary of skipped entities.

Solution: Ensure the SysAid service account has administrator privileges and read access to every entity you want to sync.

Server Errors (HTTP 500 / 502 / 503 / 504)

Transient server errors are retried automatically with exponential backoff:

• Attempt 1: Retry after 1 second

• Attempt 2: Retry after 2 seconds

• Attempt 3: Error is logged and reported

Session Expiry (HTTP 401 on Legacy API)

The legacy SysAid API uses a cookie-based session that eventually expires. The connector detects 401 responses, transparently re-authenticates, and replays the failed request.

Timeout Resumption

Every extraction worker checkpoints its progress after each page. If the ADaaS runtime signals a timeout mid-sync, the cursor is saved in state and the next invocation resumes exactly where the previous one left off — no records are re-fetched or skipped.

Best Practices

Initial Setup

1. Use a dedicated service account: Create a SysAid admin account specifically for the DevRev connection.

2. Run the initial sync in off-peak hours: A full sync is read-only but still generates API traffic. Running it outside business hours keeps bandwidth clear.

3. Test the connection first: Always click Test Connection before saving.

4. Monitor the first sync: Watch the initial sync closely to catch any permission issues early.

5. Review skipped entities: Check the sync logs for any entities that were skipped due to permissions.

Ongoing Operations

1. Schedule regular syncs: Set up hourly or daily syncs based on how fresh you need your data.

2. Monitor rate limits: Review sync logs for rate-limit warnings and adjust the schedule if needed.

3. Rotate credentials periodically: Follow your organization's password rotation policy for the service account.

4. Review sync history: Periodically check the Sync History tab for errors or warnings.

Performance Optimization

1. Let incremental sync do its job: Allow the initial full sync to complete before scheduling frequent runs.

2. Do not reset sync state casually: Resetting the sync unit triggers a fresh INITIAL run, which re-ingests everything.

3. Respect SysAid rate limits: Stagger syncs if you run multiple DevRev snap-ins against the same SysAid tenant.

4. Watch the sync log output: The Fetched N, pushed M line for assets and articles tells you how much is actually moving on each run.

Security

1. Use a dedicated service account: Do not reuse a personal admin account for the integration.

2. Limit account lifetime: Rotate credentials periodically.

3. Monitor account usage: Review SysAid's audit logs for the service account to detect anomalies.

4. Revoke if decommissioned: If you uninstall the connector, delete or disable the SysAid service account.

Troubleshooting

Connection Test Fails

Error: HTTP 401 Unauthorized

• Cause: The username or password is incorrect, or the account is locked.

• Solution: Log in to SysAid with the same credentials in a browser to confirm. Reset the password in SysAid if necessary.

Error: HTTP 404 Not Found

• Cause: The subdomain is incorrect.

• Solution: Verify your subdomain (for example, acme for https://acme.sysaidit.com). Do not include https:// or the trailing path.

Sync Fails or Is Incomplete

Symptom: Rate limit errors (HTTP 429)

• Cause: Sync frequency exceeds your SysAid API rate limits.

• Solution: Reduce sync frequency. The connector automatically delays and retries, but frequent delays can stretch sync duration.

Symptom: Entities are skipped

• Cause: The service account lacks the required permissions.

• Solution: Confirm the account is a SysAid administrator and has read access to the endpoints listed in the Prerequisites section.

Symptom: Tickets missing after an incremental sync

• Cause: Incremental mode only pushes tickets whose update_time is after the previous sync.

• Solution: If you need to re-ingest older tickets, reset the sync unit in DevRev so the next run is a full INITIAL sync.

Symptom: Asset count changes between initial and incremental runs

• Cause: Assets without an updateTime newer than the watermark are correctly filtered out on incremental runs.

• Solution: This is expected — the asset still exists in DevRev; it was just not re-pushed because it had not changed.

Sync Takes Too Long

Solution 1: Confirm incremental sync is active — look for Mode=INCREMENTAL in the first log line of the run.

Solution 2: Increase the sync interval to allow each sync to complete before the next one starts.

Solution 3: Check SysAid system health — slow server responses stretch sync times.

Knowledge Article Author Shows as a Username Instead of a Linked User

Symptom: An article's author field shows a username string rather than a user link.

Solution:

1. Make sure the author user exists in your SysAid user list and has been imported by the connector.

2. The author match is performed against name, login_user, calculated_user_name, and email_address. Confirm at least one of those matches what the createdBy field returns for the article.

3. Trigger a fresh sync after importing the missing user.

API Rate Limits

SysAid enforces API rate limits based on your license tier. The connector:

• Reads the retry-after response header on HTTP 429 to determine how long to wait.

• Pauses the sync and emits DataExtractionDelayed so the ADaaS runtime resumes it after the delay.

• Paginates every endpoint to minimize per-request payload size.

If you repeatedly see rate limit warnings, contact SysAid to review your rate limit tier.

Data Privacy and Compliance

Data Imported into DevRev

• Service request title, description, category, status, priority, timestamps, requester, assignee, company, and assigned group.

• User profile attributes (first name, last name, email, job title, department, location, phone).

• Company records with name, address, contact details, and agreement information.

• Asset inventory including owner, manufacturer, model, serial, OS, and operational flags.

• Knowledge base article title, body, author, and publish state.

• Service catalog template definitions (name, type, fields offered).

• CMDB type and relation type definitions.

Data NOT Imported

• Passwords or authentication secrets.

• Ticket attachments and article attachments (not implemented).

• Custom ticket fields beyond the documented core set.

• SLA policy definitions and software license records (SysAid does not expose these on the standard API).

• Full historical audit log (only the current state of each record is imported).

Compliance Considerations

• GDPR: Ensure your data processing agreements cover DevRev as a data processor.

• SOC 2: DevRev maintains SOC 2 Type II compliance for data handling.

• Data minimization: The connector imports only the fields documented above — no other SysAid fields are extracted.

Support

For issues with the SysAid AirSync connector:

1. Check sync logs: Review the Sync History tab for error messages and warnings.

2. Review documentation: Consult this guide and the troubleshooting section.

3. Contact DevRev Support: Open a support ticket in DevRev with:

   • Connection name

   • Sync run ID (from the Sync History tab)

   • Error messages from the sync logs

   • Steps you have already tried

For issues with SysAid credentials, API access, or rate limits, contact SysAid Support.

Limitations

• One-way sync: Data flows from SysAid to DevRev only (no write-back to SysAid).

• Read-only fields: Records are read-only in DevRev from the perspective of the sync; edits in DevRev do not propagate to SysAid.

• Attachment support: Not implemented — ticket and knowledge article attachments are not copied.

• Custom ticket fields: The connector imports the documented core fields. Heavy customization beyond that requires a scoped extension.

• Software licenses and SLAs: Not imported — SysAid does not consistently expose these via the public API.

• Historical audit log: Not imported — only the current state of each record is captured.

• Real-time sync: Polling-based; the connector does not receive webhook events from SysAid.