iHub Integration Platform

Clarizen's integration platform is used to integrate 3rd-party applications with Clarizen. 

Using iHub, Clarizen decreases the Total Cost of Ownership (TCO) for integrating external applications with Clarizen, and allows for a quick ROI by supporting:

• No additional fees or support costs
• Single entity responsibility for the entire integration 

This article should be read in conjunction with the specific integration you are using:

• Salesforce
• Jira

Jump to:

• Key features and benefits
• How it Works
• Accessing the iHub
• Setting Up Authentication
• Mappings and Triggers
  • Creating a New Mapping
  • Defining Objects
  • Enabling Social Mapping
  • Applying Templates
  • Defining Field Mapping
  • Defining Links and Relations
  • Defining Event Triggers
• Synchronization options
• Audit
• Sync logs
• iHub Notifications
• Sync registry
  • Sync Registry Import
• Settings
• Testing Jira or Salesforce Integrations 
• Refreshing a Sandbox Account
• Troubleshooting the Sync Process

Key Features and Benefits

Clarizen's features include:

• Automatic out-of-the-box integration setup (Best Practices package)
• Multiple system authentication support
• Unified user experience with core integrations
• Integration monitoring and notifications
• Manual full sync or scheduled change sync of objects between Clarizen and the integrated system
• Customizable sync processes and mapping
• Customizable event triggers
• Real-time feedback on the status of the synchronization process 

How it Works

Architecture

The iHub information structure architecture is shown in the following diagram.

iHub synchronizes entities between two systems by copying data from one system to another. The Admin defines what entities will be synchronized and what data will be copied using entity mappings.

Entity mapping

Entity mappings define the synchronization between objects in Clarizen and the integrated system. This includes:

1. Entity keys for objects define the key field for each entity (object). Generally it should be the unique entity identifier that shares the same value in both systems. For example email address for user, company domain name, etc.
2. Field mapping entity fields - a list of field pairs that define which fields will be copied to which fields on the other system. There are three types:
1. Create only - a field value will be copied only once the entity is created
2. Sync only - a field value will not be copied when an entity is created, but will be copied each time it is synchronized after that.
3. Create & sync - a field value will be synchronized in all cases.
3. Clarizen Link creation allows linking a newly created Clarizen entity with another entity.
4. Relations for both systems - defines what related entities will be synchronized for given entities. For example, a user can define that when a project is synchronized, all its active tasks should be synchronized as well. Relations can be defined for both systems.
5. Synchronization fields for both systems.

Triggers

Entities can be synchronized between systems using one of the following methods:

• Clarizen trigger
• External system trigger
• Manual sync 
• Sync Now (from Clarizen or from integrated system)
• Scheduled sync

Accessing the iHub

The iHub is easily accessed by Admin users from Clarizen's Extensions Settings

To access the iHub:

1. As an Admin user, open Clarizen Settings from under your username. 
2. Open the Extensions tab.
   A list of applications and purchased integrations appears at the bottom of the page.
   
3. If the integration was not yet activated, click Allow Access adjacent to the required integration to enable the integration.
4. Click Open for the relevant integration.
    

Setting Up Authentication

iHub provides a flexible authentication mechanism based on the integrated application requirements for a one-time authentication setup process.

All of the integration's security options are saved in Clarizen for a seamless workflow between Clarizen and the the 3rd-party integrated applications.

Depending on the integrated application, Clarizen will use appropriate authentication methods to access resources of the integrated application. Available methods include:

• OAuth Single Sign On versions 1 and 2
  • Oauth gives access to an external application with existing credentials
  • Authentication to iHub is set up in the integrated application (such as Salesforce), management of sync and field mapping can occur in the iHub within Clarizen or from within the integrated application
• Logon Authentication where a username and password is required to access resources in their application

To define OAuth authentication:

1. Access the integrated system as an Admin user (such as Salesforce).
2. Enable the integration.
3. Define the User.
4. In Clarizen, open iHub as explained above

   Note: This may happen automatically depending on the integration type.

5. Open the Authentication tab.
   
   Your 3rd-party credentials should appear on top.
6. Define your Clarizen credentials. Click Add Clarizen credentials to add users allowed to use the integration.
   Note: At any time you can disable or delete users from the list by selecting the user(s) and clicking the relevant link below the list. Select a user and click Change credentials to change a user's login information.

To define Logon authentication:

1. In Clarizen, open iHub as explained above
2. Open the Authentication tab.
   

   Note: If this is the first time you are setting up the authentication, the screen will look like this:
   

3. Under the integrated system section:
   1. Set your Company ID (if applicable)
   2. Enter your username
   3. Enter your password
   4. Click Login.
      Note: Use the Admin credentials of the integrated application.
4. Under the Clarizen section, click Add Clarizen to add users allowed to use the integration.

Note: At any time you can disable or delete users from the list by selecting the user(s) and clicking the relevant link below the list. Select a user and click Change credentials to change a user's login information.

Mappings and Event Triggers

All of Clarizen's integrations are based on connecting (or mapping) objects and fields in Clarizen to objects and fields in the integrated system.

Once the system is mapped properly and the objects and fields in the two system are connected, event triggers can be defined to create field-specific synchronization based on activity in one or both systems. For example, in an integration with Jira, a bug created in Jira can create a bug in Clarizen, and in an integration with Salesforce, a project can be automatically created in Clarizen once a lead lifecycle in Salesforce is marked done, etc.

The initial setup of the integrated system in iHub includes automatic synchronization of out-of-the-box object and field mappings and event triggers between Clarizen and the integrated system (Best Practices package). Most integrations allow you to then customize and edit these mappings and triggers, however some integrations require Professional Services assistance for initial (or editing) mapping and triggers. Depending on the integration, the Professional Services team required may be Clarizen's (such as for Salesforce integration) or the integrated application.

Objects between the integrated system and Clarizen can be set as bi-directional while specific field mappings follow the Master-Slave synchronization behavior, where one system is defined as the Master and the other as the Slave. To create bi-directional field mapping you will need to define the field twice, once with Clarizen as the master and once with Clarizen as the slave. 

Creating a New Mapping

In the Mapping & Events tab you can define the various mappings and event triggers used in the system, as well as the daily sync activity between the systems and initiate a manual sync process.

You can export the object & field mapping to back up your settings, and with the import option, you can easily implement your settings on multiple platforms, for example when moving from a sandbox environment to production.

Note: When packaging mappings and events, you must package mappings and events separately, so that you can first load the mappings, and then the events. Some events will not load properly if the mappings do not exist.

Even after changing or creating various new mappings, you can always utilize the default settings by clicking Apply Best Practices, which will import all of the default out-of-the-box best practices without overriding the work you have already done in personalizing the mapping end event settings.

To create a new mapping:

1. Click Add new under the Mapping list.
2. Give the mapping a clear Name.
3. For additional information use the Description field.
   
4. Continue with the following steps:
   1. Define the Object mapping as described below
   2. If applicable, enable Social feed synchronization.
   3. For project mapping you can apply templates.
   4. Define the specific field mapping for the object as described below
   5. Set the various (optional) additional settings.
5. Click Save to save the changes made and close the window.

To edit or delete an existing mapping:

1. Click Disable adjacent to the relevant object in to stop the selected object from synchronizing.
2. Click Delete adjacent to the relevant object to delete it completely.
3. For specific edits, open the mapping editor by clicking the Edit link adjacent to the relevant object (or the object itself).
4. Edit the relevant section you wish to edit.
5. Click Save. 

Defining Mapping Objects

Define the object mapping in Clarizen and in the 3rd-party integration system. Object mappings can be created for any entity in Clarizen, including custom fields.

Field mappings on the object level can either be created or retained in the respective systems depending on the Master-Slave relationship.

• If the field exists in the Master and not in the Slave, it can be created and synchronized in the Slave.
• If the field exists in the Slave but not in the Master it can be deleted or retained in the Master.
• If both fields exists then they can be synchronized.

To define the object mapping:

1. Select the Entity to be synchronized in both Clarizen and in the integrated system.
2. Based on the selected entity, select the associated Key Field used as an identifier.
3. Define the Deletion policy for both systems in the Delete Policy menu.
   The deletion policy determines whether the field will be deleted or retained in Clarizen, or the integrated system if it was deleted from the other.
4. Define the creation policy for both systems in the Create Policy menu.
   The Creation policy determines whether the field is to be created in Clarizen or the integrated system when it does not exist, and was referenced in a separate mapping or event trigger.

Applying Templates

When mapping a project entity, you can apply templates to the project created and even apply a set of preset conditions to determine which template to use.

To apply templates:

1. Select the Object entity in Clarizen as explained above
2. Click+ to open the Template Rules section.
3. Click Add Template.
   
   
4. Select a template from the list of available templates in your organization.
5. Create rule(s) for the selected template (optional).
6. Click Add Template to add additional conditional templates.
7. When using multiple templates, select the order in which the rules are applied.
   Select the checkbox next to one of the templates and use the Arrow button to move the selected template.

Enabling Social mapping

Social syncs are performed every 10 minutes provided that the integrated application has a corresponding, accessible API, and that the social sync checkbox is selected in the object mapping. 

Defining Field Mapping

Some objects may have more than one information field associated with it.

Once the object is defined, you need to define all of the relevant fields associated with that object, and define the synchronization process between the two systems.

To define the field mapping:

Note: When creating new field mappings, the fields will not retroactively update records that were already created. Those records should be manually synced.

1. Select the Object entity in Clarizen as explained above
2. Click+ to open the Field Mapping section.
   
3. Define the sync Direction. 
   • From Clarizen - defines Clarizen as the Master and synchronizes the data from Clarizen to the integrated system
   • To Clarizen -  defines Clarizen as the Slave and synchronizes the data from the integrated system to Clarizen 
4. Select the integrated system field name from the list.
   The list is automatically filtered based on the defined entity.
5. Select Clarizen's field name from the list.
   The list is automatically filtered based on the defined entity.
6. In the Event Type menu, define whether to create, synchronize, or create & sync the data in the direction defined in step 3.

   Note: Create is normally used only for the initial process where you want to ensure that all fields are available in both systems.

7. Click Add to define additional fields.
8. Repeat steps 3-7 for all of the relevant fields associated with the defined object. 

Defining Links and Relations

Clarizen allows you to link and associate related objects as part of the process. In addition you can populate fields both in Clarizen and the integrated system with the synchronization status and date for easy monitoring of the sync process. 

Clarizen Links

You can link the mapped Clarizen object to additional objects in Clarizen when a new object is created. For example, link a newly created project to the relevant customer.

To create Clarizen links:

1. Select the Object entity in Clarizen as explained above
2. Click + to open the Create Clarizen Links section. 
3. Click Add. 
   
   
4. Link the defined object to an object from the Link to list.
5. Some objects may require a linking method.
   Select the linking method from the using list.
6. Define whether to use a Source Object Field from the available list or an evaluation criteria identifier.
   • Use source object field - Select a field from the relevant object in Clarizen.
     This option requires a mapping between the two item types and will utilize the Object Mapping definition (above) to locate the object in Clarizen.
     The link will be created for the object within Clarizen and synced to the object referenced by that field.
     If the selected object is not synced to Clarizen, it may be created if the Clarizen Create Policy is Create in the relevant object mapping.
   • Identified by - ​Allows you to add evaluation criteria which will determine what object in Clarizen to link to.
     
7. Click Add to define additional links.
8. Repeat steps 4-6 for all required links. 

Clarizen Relations

Clarizen relations allows you to map multiple relations to an object in the integrated system.

To define relations:

1. Select the Object entity in Clarizen as explained above
2. Click + to open the Map Related Clarizen Objects section.
3. Click Add Related Object.
   
   
4. Define the Related object.
5. Define the Relationship type.
6. To use conditions:
   • Click Add. 
   • Define the desired conditions.
   • When using multiple conditions, you can define the logical expression as either AND (default), or OR. 
7. Select an object in the integrated system to map.
   A link will appear to either view the object mapping if mapping was already defined or to create a new object mapping. In both cases the mapping editor is opened where you can view the mapping settings or complete the same process for the rest of the mapping options for a new mapping.
8. Click Add Related Object to create an additional relation mapping.
9. Repeat steps 4-7 for each of the relations.

Synchronization Fields Mapping

You can define fields in both Clarizen and the integrated system for the purpose of monitoring your sync process.

If sync monitoring on the object is required, we recommend using custom fields created for this purpose.

To set sync field mapping:

1. Select a field to be populated by the Sync status in the integrated system.
2. Select a field to be populated by the Sync status in Clarizen.
3. Select a field to be populated by the Sync date in the integrated system.
4. Select a field to be populated by the Sync date in Clarizen.

Defining Event Triggers

Object creation in Clarizen can be triggered by events in the integrated system and vice versa.

The events can be defined with or without conditions to create a seamless workflow between the systems.

To create a new trigger:

1. Click Add New under the Event trigger list.
   
   
2. Give the trigger a clear name.
3. For additional information use the description field.
4. Define the system in which the trigger should occur.

   Note: The various trigger options may differ depending on the integrated system you are defining.

   
   
5. Select the triggering object.
6. Define the condition rules.
7. Define the object to be created due to the condition.
8. Add relations (if available), see above for instructions
9. Click Create to complete the process and close the editor.

To edit an existing trigger:

1. Click Disable adjacent to the relevant trigger to stop the trigger function.
2. Click Delete adjacent to the relevant trigger to delete it completely.
3. For specific edits, open the trigger editor by clicking the Edit link adjacent to the relevant trigger (or the trigger itself).
4. Make the desired changes
5. Click Update to save the changes and close the editor.

Synchronization options

In addition to the event trigger sync you have the option to define up to two daily sync processes or initiate a sync manually.

The sync process is located in the Mapping & Event tab.

Click Sync Now to initiate a manual sync process, which affects all of the data defined to be synchronized.

The daily sync process only synchronizes changes to the mapped fields that have occurred since the previous sync process.

To define a daily sync:

1. Select the checkbox for the relevant sync process.
2. Define the time to start the sync process.

Audit

The Audit tab includes a log for mappings. Easily trace previous mapping changes to help in troubleshooting and verification scenarios. The last 100 updates to mappings are available.

Audit details include the mapping name, action type (create, modify, etc.), user, date, old and new values.

Sync logs

The Logs tab displays a log of all the trigger sync statuess for every time the integrated and Clarizen systems are synchronized.

The Log toolbar includes the following options:

• Clarizen Organization name - allows you to select the relevant Clarizen Organization, specifically for integrations allowing multiple organization synchronizations
• Filter the the information shown in the log table using the Show menu. The options include:
  • All
  • Failed - Objects that encountered a serious error and were not able to complete the synch process
  • Partially succeeded - Objects successfully synchronized however the synch process for one or more associated objects were unsuccessful
  • Not succeeded - Objects with a Failure, Partial Success, or Pending Retry status
  • Success - Objects successfully synchronized
  
• Refresh - click Refresh to view the latest log sync data
• Global Search box - enables you to search for specific items in the logs

The Log table includes the following information:

• Scheduling Icon  shows whether the sync item is scheduled, lines without icons represent syncs based on event triggers
• The Status icons - this icon appears for pending synchronization processes and errors that occurred in the sync process
  If no icon appears then the sync process completed successfully
  • The System will retry the sync 5 times during which time the sync is considered as pending an will display an Amber icon 
  • If on the fifth time it does not work the sync will be taken out of the process and will be considered unsuccessful and will display a Red icon 
• Date filter - the Date of the sync can be filtered to display specific dates in the log table
  
• Trigger name as defined in the Mappings and Triggers editor
• Clarizen Types, such as Project, User, or Customer
• Clarizen object - objects may be hyperlinked in order to allow you to access the actual Clarizen object

  Note: Not all Clarizen objects support hyperlinks.

• Integrated system type names
• Integrated system object names
• Messages describing the sync status type as well as additional status related information

You can also export the logs to Excel to manage and analyze your sync log.

iHub Notifications

Administrators can configure email notifications for different iHub events.

Notifications can be configured for the following events:

1. Scheduled sync
   • None - Receive no notifications.
   • Any scheduled sync - Receive a notification when any scheduled sync has been completed with full details and log file attached.
   • Only when objects fail - Only receive a notification when any objects have failed in a scheduled sync.
   • Only when objects partially succeeded - Receive a notification when any object has only partially succeeded. (Partial success occurs when the syncing of an object’s related items has failed).
2. Event triggers
   • Fail - Receive a notification when an event trigger has failed.
   • Partial success - Receive a notification when an event trigger has only partially succeeded. (Partial success occurs when the syncing of an object’s related items has failed).
3. General system errors (authentication/communication) - Receive a notification when a general error has occurred, such as an authentication error - invalid credentials that have been entered is preventing successful authentication. For new integrations, this notification is enabled by default and is sent every time a system error occurs.

Here is a sample email notification for a scheduled sync:

To manage iHub email notifications:

1. Go to Settings > Extensions > Open (app you want to configure notifications for).
   
2. Click Settings.
3. Under Notifications, choose the cases in which you want to receive email notifications.
   
4. Under Send To, check the box to receive the notifications in your inbox (as the Clarizen administrator who is currently logged in). You can also add other email account(s) the notifications should be sent to.

Note: The Other Email input box accepts semicolon-separated values.