Configuring a Connection

    Refer to our step-by-step Getting Started guide to begin your synchronization journey.

    Configuring a Connection in Visual Mode

    Configure the Sync (Scope)

    1. Click Configure Sync to start configuring the connection.

    You can even configure an existing connection by navigating to the Connections tab. Then click the Edit Connection icon in front of the Connection name.    

    2. Select Project on both sides.
    Select the projects you want to use for the Connection, at both ends.

    3. Click Filter entities (Optional)

    With this option, you can decide what information must be synchronized.

    If no option is selected, by default all the entities will be synced. 

    Set the Filters

    Select the appropriate filter you want from the list. For instance, for Jira, you can choose to sync all Bugs, Tasks that have a label = 'totest'.
    Filters for Jira:

    You can also choose to have multiple filter options.

    Example 1: 

    Issue type = Bug
    Priority = High, Medium
    Status = Open

    In this case, the Priority filter has 2 options. 

    So the options you select will be considered as an OR operation, High OR Low.

    With 2 different filter types, Issue type and Priority, the options you select will be considered as an AND operation.

    So, there are 2 possible combinations for the above sync:

    1) Bug with High priority AND Open status,

    2) Bug with the Medium priority AND Open status.

    Example 2:
    If there are no options selected for the Issue type, like in the example below:

    Priority = High, Medium
    Status = Open

    All issue types with the Priority High OR Medium and status Open will be synced.

    Filters for Azure DevOps:

    Filter example:

    Type = Task, Issue
    State = To do, Doing
    Priority = 1

    In this case, the following combinations will be synced:

    1) Task with the To do status and priority 1

    2) Task with the Doing status and priority 1

    3) Issue with the To do status and priority 1

    4) Issue with the Doing status and priority 1

    Filters for Zendesk:

    Filter example:

    Status = Open, Hold
    Type = Task
    Priority = Urgent

    In this case, the following combinations will be synced:

    1) Task with an Open status and Urgent priority

    2) Task with the Hold status and Urgent priority

    4. Set the Sync Method

    This option allows you to decide how information must be synced between the task management systems. You can choose from the following options:
    Manual
    The issue will be synchronized manually.
    Automatic
    The issue will be synchronized automatically based on the entities you have filtered in the previous step.
    Disabled
    The synchronization will be disabled.
    The arrows decide the direction of the synchronization.

    5. Click Next to configure the field mappings.  

    Add the Field Mappings (Rules)

    Rules denote the mapping between different entities & decide what must be synchronized. There are predefined default mappings for basic fields in every Visual mode Connection.

    You can access these mappings by clicking Next after configuring the sync. The Rules section consists of these mappings. 

    The actual mappings will depend on the platforms under sync. 

    The top bar displays the local instance's short name & the remote instance's short name. These are the names you provided while setting up a connection.

    It also has a Sync direction. The arrows indicate the direction, whether uni or bi-directional. You can choose to Expand all or Collapse all the mappings. 

    You can Edit connection or Delete mapping You can also drag and drop them, up or down to re-prioritize.

    Edit Mappings

    For instance, if you want to edit the Tags ↔ Labels mapping, click the Edit mapping icon

    An Edit mapping dialog box will open.


    Select the new fields to be mapped on both sides from the drop-down list. You can also edit the Sync direction. Sync direction allows you to control your sync in a specific direction, where the arrows indicate the direction.

    Click Save to apply the changes.

    Delete Mappings

    You can delete a certain mapping if you don't want it. 

    Clicking the bin icon opens up a prompt to ensure you really want to delete the mapping. Click Delete to confirm the deletion. 

    Add New Mappings 

    To add a new mapping, click the Add mapping button.


    An Add mapping dialog box will open.

    Select the required fields at both ends from a drop-down list. You can choose to keep the Sync direction as it is by default or edit it. Sync direction allows you to control your sync in a specific direction, where the arrows indicate the direction.

    You can add sub-mappings by clicking the plus icon.

    You can also specify what to do if the selected values do not match.

    If no matching value is found you can choose to: 

    Option

    If the value doesn't exist

    Set a default valueFields will be set to a default value you specify
    Report an errorAn error will appear & be displayed on the Errors tab. The synchronization will be blocked in this case. 
    Do nothingThe values stay the same

    Save the changes whenever you are ready. 

    Custom field mappings

    When you set up a Visual mode connection, Exalate fetches some of the custom fields for you. These are available through a drop-down list while adding a mapping. 

    If you don't find the custom field, there is always an option to add Scripts

    The following are the supported custom field types:

    Text:
    * Jira Cloud: Text Field (multi-line), Text Field (single line)
    * ADO: Text (single line), Text (multiple lines)
    * Zendesk: Text, Multi-line, Date, Number, Decimal

    Option:
    * Jira Cloud: Radio Buttons, Select List (single choice)
    * ADO: Picklist (string), Picklist (integer)
    * Zendesk: Drop-down

    User:
    * Jira Cloud, on-prem: User Picker (single user)
    * ADO: Identity
    * Zendesk: - Not supported

    Add Scripts for Advanced Configuration (Optional)

    For advanced synchronization use cases, you can add Groovy Scripts to your Visual mode Connection. 

    To do so, click the arrow on the Add Mapping button. Select Add Script.

    There will be a default Script in the dialog box. You can edit it or simply delete the entire Script to start writing from scratch. Click Save when you finish adding the Scripts. 

    Script Syntax: 

    As a general rule of thumb, the Scripts follow the following syntax:

    your_instance_shortname.issue.customFields."your custom field name".value = remote.issue.customFields."remote custom field name".value

    Where, 

    1. your_instance_shortname is the source instance. 

    2. remote_instance_shortname is the destination instance. 

    These are the names you provided while setting up the Connection. 

    3. This is followed by other issue properties, each separated with a "." operator. 

    Publish the Changes 

    To save the changes made to the Scope and Rules section and apply them to the Connection you have created, click Publish

    You can also use these hotkeys to publish a connection:

    • Ctrl+S on Windows or Linux
    • Cmd+S on Mac

    Configuration changes made to the Connection will be applied on the next synchronization.

    Configuring a Connection in Script Mode

    You can configure a connection in Script mode by modifying the Sync Rules (or Rules) and setting up automatics sync Triggers

    Configure the Sync Rules (or Rules)

    Exalate uses synchronization rules to handle outgoing and incoming messages. We call them Sync Rules. You can find Sync Rules in a separate tab when you select the connection to edit.

    How to create a Sync Rule?

    Sync rules are Groovy-based scripts that can be used to implement filtering, mapping, and transformation. These are essential operations in any synchronization.

    Groovy is a dynamic language for the Java platform. Check out the following links to get more details about Groovy and how to develop in this language:

    Groovy learning courses that we can recommend:

    Sync rules types

    There are 2 different types in the Sync Rules. Each with its own purpose. 

    Outgoing Sync

    Defines what information is sent to the destination side.

    Exalate runs the outgoing sync processor when you start the synchronization or update the local issue which is under sync.

    You can assign entity fields to a replica on the outgoing sync. 


    Variable

    Explanation

    Inputissuelocal issue data you need to synchronize.
    Outputreplicacopy of the issue data which will be sent to the destination instance.

    Examples:

    replica.summary     = issue.summary // send summary
    replica.description = issue.description // send description
    replica.comments    = issue.comments // send comments
    replica.attachments = issue.attachments // send attachments

    Condition example in the Outgoing Sync rules

    Don't send anything if the priority is trivial. 

    // If the issue priority is "Trivial" don't send any data. In other cases send the summary, description, comments and attachments
     
    if (issue.priority.name == "Trivial") {
        return
    }
    replica.summary     = issue.summary
    replica.description = issue.description 
    replica.comments    = issue.comments
    replica.attachments = issue.attachments

    Incoming Sync

    When you receive data from the other side you need to apply this data to your instance. You can define how to handle the received information on your instance with the help of the incoming sync rules.

    Exalate runs the incoming sync every time there's new data received from the remote side.  

    When you receive the synchronization data from the remote side for the first time, Exalate creates the issue locally in your instance.

    Starting from this moment the issue is considered under synchronization(under sync). From that moment every issue update will trigger the update of the synced issue on the other side. 


    Variable

    Explanation

    Inputreplicainformation received from the source instance.

    previousprevious information received from the source instance.
    Outputissueissue object which will be used to create/update the local issue.

    When you leave the incoming sync empty, then nothing is synchronized. 

    Simple Incoming Sync Example:

    if(firstSync){
       // If it's the first sync for an issue and local copy of the issue does not exist yet
       // Set project key from source issue, if not found set a default
       issue.projectKey   = nodeHelper.getProject(replica.project?.key)?.key ?: "TEST"
       // Set type name from source issue, if not found set a default
       issue.typeName     = nodeHelper.getIssueType(replica.type?.name, issue.projectKey)?.name ?: "Task"
    }
    issue.summary      = replica.summary
    issue.description  = replica.description
    issue.comments     = commentHelper.mergeComments(issue, replica)
    issue.attachments  = attachmentHelper.mergeAttachments(issue, replica)

     Incoming requests are distinguished based on the information stored in a replica.

    So if you want to have different sync rules for the first synchronization and then others for synced issue updates you should use conditional statements


    if (firstSync) {
      return // don't create any issues, only sync changes to the issue which are already under sync
    }
    issue.summary = replica.summary
    issue.description = replica.description
    issue.labels = replica.labels
    issue.comments = commentHelper.mergeComments(issue, replica)
    issue.comments = attachmentHelper.mergeAttachments(issue, replica)

    More advanced configuration

    You can set your own values for the local issue based on the received data from the other side. 

    For example, if the synced issue status changes to Done on the remote side → set the local issue status to Resolved.

    To configure advanced conditions for your synchronization use script helper methods.

    Check the example below.


    // Create a request in the support project "SD", but if it's a critical issue in the customer's WEB project, assign it to Kevin Spacey
      
    issue.project = nodeHelper.getProject("SD")
     
    if (replica.priority.name = "Critical" && replica.project.key = "WEB") {
        issue.assignee = nodeHelper.getUser("kspacey") // assign to Kevin
        issue.priority = nodeHelper.getPriority("Blocker")
    } else {
        issue.priority = nodeHelper.getPriority("Major")
    }
      
    issue.summary = replica.summary
    issue.projectKey = "SD"
    issue.typeName = "Request"
    
    

    Set-up Automatic SyncTriggers

    Learn how to set up automatic sync triggers

    Publish the Changes 

    To save the changes made to the Sync Rules and Triggers section and apply them to the Connection you have created, click Publish

    You can also use these hotkeys to publish a connection:

    • Ctrl+S on Windows or Linux
    • Cmd+S on Mac

    Configuration changes made to the Connection will be applied on the next synchronization.

    What's Next?