Environments Sync Mode

Introduction

This article explains the Environments Sync Mode functionality in ONEiO. In case you have questions related to setting up the integration, send a mail to the ONEiO support team at support@oneio.cloud.

1. Overview
2. Step-by-Step
   1. Step 1 - Select the direction for the sync or to move configurations
   2. Step 2 - Select objects to be synced
   3. Step 3 - Preview the changes and configurations after the sync
3. Best Practices
   1. When syncing an entire set of objects from QA to PROD
   2. When updating endpoints
   3. When updating rules
4. Frequently Asked Questions

Overview 

The Environments sync mode functionality provides the user the capability to move endpoint and routing rules configurations between QA and PROD environments within a subscription. The typical uses cases are the following:

• Moving new endpoints and routing rules from the QA to the PROD environment. This creates a copy of those objects in the PROD environment. Routing rules will be left disabled and endpoints in suspended mode. This process is your main go-to tool for your go-live procedure and also facilitates expansion of business cases when new rules and endpoint configurations (new entity types, message types and attributes) are added to further integrate new processes.
  
  
• Moving the updated routing rules and endpoints in QA to update their paired/corresponding target objects in PROD. This results in updates to the objects; with new versions of the routing rule(s) and/or a configuration update to the endpoint(s). The enabled/disabled state of the rule remains the same and the endpoint state, whether active/suspended, remains as-is. This process is the recommended way to first test changes in QA and move those changes into PROD, and also the best way to update the integration when requirements change.
  
  
• Back porting changes made to routing rules and endpoints in PROD to update their paired/corresponding target objects in QA. This updates the objects with new versions of the routing rule and/or a configuration update to the endpoints. A use case will be moving changes back to QA after a hot fix was applied in PROD to keep things in sync. It is still recommended to test and validate in QA first unless the situation calls for such a change.
  
  
• Moving new endpoints and new routing rules from PROD to QA creates a copy of the selected PROD objects moved to QA. Though the capability exists, it is not the ideal process as integrations are first built and tested in QA before moving to PROD.

Step-by-Step

We will illustrate the process by moving configurations of already existing endpoints and new routing rules from QA to PROD and also moving changes in rules from QA to their PROD paired target object.

To access the Sync mode, click on the Environments icon () on the top right corner of the page and then click on the text Sync mode. 

Access the Sync Mode

The sync mode plays out in three stages:

• Select the direction to move the configurations; either from QA to PROD or from PROD to QA
• Select objects to be synced
• Preview the changes and configurations after the sync

STEP 1 - Select the direction for the sync or to move configurations

Clicking on Sync Mode, a pop-up window opens, requiring you to choose the direction to move the configurations.

As shown in the screenshot below, the Sync Mode displays a series of steps at the bottom of the screen. These steps outline the synchronizations process and indicate the current active step. To proceed to the next step, select "Next," or choose "Back" to go back to the previous step at the bottom of the page. 

Choosing the direction - QA -> PROD

STEP 2 - Select objects to be synced

Within the second step before you select objects to be moved, you can still check the differences between each object. The icon()indicates the objects have differences and are out of sync (labeled 1 and 3 in the screenshot below for endpoint configurations and routing rules respectively) and will have the checkbox. Clicking on this icon, and "see differences", will redirect you to the Differences View.

Sync status icons()will indicate the objects are in sync and cannot not be selected; hence no checkbox(labeled 2 in screenshot below). Objects with icons() will indicate there is no paired object in the target environment so when the object is moved, a new copy of the object is created (labeled 4 in screenshot below).

Sync statuses in step 2 - selecting objects to move

Click the checkbox of each object you wish to select for syncing.

• Clicking on the icon (bottom arrow) will detail the sync status of the whole Endpoint, including Entity Type, message type, and Routing Rules. Each row has its own sync status, because there could be the case when an entity type has no paired object, but the whole Endpoint configuration is in-sync (or out-of-sync). If one of the entity types or endpoint is out of sync then all of those objects are out of sync because they are currently part of the same configuration.
  
  

• It is not possible to sync individual entity types or message types. Checking the box of any endpoint object selects the whole endpoint (labeled 1 below), except for its Routing Rules.
  
  

• You can either select all Routing rules related to a specific outbound endpoint by clicking in the check box next to the object labeled Routing Rule or select individual routing rules as seen in the screenshot below.
  
  

• In this example, the selected rules will be updated in PROD by adding new versions to each of the rules (labeled 2 in the screenshot). New rules will be created in the PROD environment (labeled 3 below).

Selecting specific objects to move

STEP 3 - Preview the changes and configurations after the sync

The third step shows you the preview of what the objects being moved would look like in PROD. All sync status icons of the objects will all still remain as arrows. Click Confirm.

Preview of synced objects

After confirming you will get a first sync status message at the top of the page: The synchronization process was initiated. Please wait.

Sync process has initiated

Depend on the number of objects being synced, it may take a couple of seconds and when the sync is complete, you get a successful sync message at the top of the page. 

Sync complete

The page will refresh automatically to general Environment view page to see all the items that have now been synced successfully.

Synced status after refreshing

BEST PRACTICES

When syncing an entire set of objects from QA to PROD

Before

• Ensure that your configuration is tested in your QA environments and ready to go to production.
• Take note of any objects or properties that may need to be adjusted in the PROD environment.

After

• Navigate to the PROD environment and add the needed URL and credentials for your endpoints to work you can refer to the FAQ for properties that are ignored in the sync.
• Enable the endpoints and the rules that you have synced when you are ready to go live.
  
  

When updating endpoints

Before

• Use the differences view first to see what the differences in your configurations are and what you will be synchronizing.

After

• Check and adjust any of properties that are not ignored in the sync and update them if they are environment specific.

When updating rules

Before

• Use the differences view first to see what the differences in your configurations are and what you will be synchronizing.

After

• Check and adjust any of properties that are not ignored in the sync and update them if they are environment specific.

Frequently Asked Questions

• Why are my endpoints / message types / entity types / routing rules appear to be out of sync even if the differences view does not show any differences?
  Initially all objects will be out of sync until they have been synced for the first time. Simply sync the objects once and they will then be tracked for any changes that have been made after the sync.
  We recommend to sync from PROD to QA first to avoid any production issues if some object properties were adjusted by the sync (these differences should be highlighted in the differences view).
  
  
• What if I sync endpoints or routing rules that I did not want to be synced?
  You can do a partial rollback through the user interface.
  For routing rules, you can revert back to a previous version of a rule by going to the routing rules view and changing the current version.
  
  For endpoints, it is not possible to revert to an older version of an endpoint. If you know the changes that were made in the sync, you can always change the values to the previous values.
  
  Our support is also able to rollback a version of an endpoint. You can contact us at support@oneio.cloud and we will further assist you and investigate the issue.
  
  
• What happens to the different statuses of each of the objects when syncing?
  When you are moving new endpoints or routing rules, they are disabled when synced. This ensures that you can update any environment specific properties and that you are confident to go live with the changes.
  When syncing existing objects, the statuses of the objects will remain as they were in each of the environments.
  
  
• What happens to the attributes or values that may be different between the environments?
  Some properties are unique to the environment, for example custom fields in Jira, timezones for instances of ServiceNow and URLs and credentials for an endpoint. There’s unfortunately no way to currently manage these types of properties as of now.
  
  Some properties have been considered as properties that should not be synced. These properties will not be synced to the other environment in an initial sync and are either left empty or set with the value “TODO” and will be ignored in any consecutive synchronizations.
  
  Properties that will not be synced and are ignored:
• • When an endpoint is created as a result of the sync the following fields should be set manually:
    • • url
      • usernames
      • passwords
      • OAuth2 Client Id
      • OAuth2 Client Secret
      • OAuth2 Token URL
      • OAuth2 Additional Parameters
      • "security.pem.value"
      • "security.authentication.clientCertificate.data"
      • "security.authentication.clientCertificate.password"
      • "security.authentication.token.authenticationUri"
      • "receiver.polling.integration.user"
      • "receiver.certificate.value"
      • "receiver.ipAllowList"
      • "receiver.polling.enabled" = false (by default)
        
        
  • When an endpoint is updated as a result of the sync all the fields are synced except:
    • url
    • usernames
    • passwords
    • OAuth2 Client Id
    • OAuth2 Client Secret
    • OAuth2 Token URL
    • OAuth2 Additional Parameters
    • "security.pem.value"
    • "security.authentication.clientCertificate.data"
    • "security.authentication.clientCertificate.password"
    • "security.authentication.token.authenticationUri"
    • "receiver.polling.integration.user"
    • "receiver.certificate.value"
    • "receiver.ipAllowList"
      
• What if I already have objects in both environments, e.g. my Jira already exists in both QA and PROD, but they are not connected to each other?
  We have done our best to pair all of the objects in your environments. If you notice that some objects are not paired with each other or they are paired to the wrong object, please reach out to our support@oneio.cloud to pair the objects correctly.
  
  
• I initiated the sync and I cannot see any changes to either environment
  First try to refresh your browser. The view does not automatically update with the changes. It can take up to 10 seconds for the synchronization to be complete, depending on the number of objects you are syncing.
  
  
• I received an error for my sync, what now?
  If your syncing resulted in an error, none of the objects will be synced. You can try the sync action again, or sync changes partially. When an error persists, please contact our support team at support@oneio.cloud and we will further assist you and investigate the issue.