16.1 iHub Integration Platform

iHub Integration Platform

This article describes Clarizen's integration platform used to integrate 3rd party applications with Clarizen and explains the various features and usability of the iHub in general terms.
This should be read in conjunction with the specific integration you are using in order to get the complete picture of your integration.
The information on the specific integrations can be found in this chapter.

The page covers the following:

 

Overview

The Integration Hub (iHub) facilitates the synchronization of objects between 3rd party systems (SaaS or on-premise) and Clarizen, providing an automated Sync process that includes the ability to synchronize virtually any information depending on the versatility of the integrated system.

The iHub is a flexible and customizable tool allowing us at Clarizen to manage and create integrations with various supportive applications

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
  • One entity responsibility for the entire integration

 

iHub Architecture

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

 

Key features and benefits

Clarizen's iHub delivers many benefits and is loaded with features including:

  • Automatic out of the box integration setup
  • 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

 

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 either the masthead or the navigation panel.
  2. Open the Extensions tab
    The various applications and purchased integrations list 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 any of the available integrations to access the iHub

 

 

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, the available methods include:

  • OAuth Single Sign On version 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 user name 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 or Wave)
  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 being defined.

  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
    • At any time you can Delete or Disable 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 the authentication, the screen will look as follows:

  3. Under the integrated application section:
    • Set your Company ID (if applicable)
    • Type your User name in the appropriate field
    • Type your Password in the appropriate field
    • Click Login
      Note:

      The credentials used must be set as an Admin in the integrated application.

  4. Under the Clarizen section:
    • Click Add Clarizen credentials to add users allowed to use the integration
    • At any time you can Delete or Disable 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: an invoice can be issued in Intaact once a project is marked complete in Clarizen, a project can be automatically created in Clarizen once a lead lifecycle in Salesforce is marked done, etc.

The initial set up of the integrated system in the iHub includes automatic synchronization of out-of-the-box object and field mappings and event triggers between Clarizen and the integrated system, 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 PS team required may be Clarizen's (such as for Salesforce integration) or the integrated application (such as McKinsey for Wave integration)

Objects between the integrated system and Clarizen can be set as bi-directional while specific field mappings follows 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.

 

Mapping - General

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

Clarizen allows you to export the object & field mapping in order to backup your settings, in addition together with the import option, you can easily implement your settings on multiple platforms, for example when moving from the training box (or sandbox) environments into production.

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

To edit an existing mapping:
  1. Click Disable adjacent to the relevant object in order 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)
    The mapping editor window opens
  4. Edit the relevant section you wish to edit, see ahead for complete details on each of the sections
  5. Click  to save the changes made and close the window

 

 

To create a new mapping:
  1. Click the  button located under the Mapping list to create a new mapping
    The Mapping editor opens
  2. Give the mapping a clear name
  3. For additional information use the description field
  4. Define the Object mapping as described below
  5. If applicable enable Social feed synchronization
  6. For project mapping you can apply templates 
  7. Define the specific field mapping for the object as described below
  8. Set the various (optional) additional settings
  9. Click  to save the changes made and close the window

 

 

Mapping details - Objects

Define the object mapping in Clarizen and the 3rd party integration system.

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

Object mapping can be created for any entity in Clarizen, including custom fields.

To define the object mapping:
  1. Select the Entity to be synchronized in both Clarizen and the integration 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 should be created in Clarizen or the integrated system if 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. Open the Template Rules section by clicking the + sign 
  3. Click 
    The template editor opens
  4. Select a template from the list of available templates in your organization
  5. Create rule(s) for the use of the selected template (optional)
  6. Click  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

 

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.

 

Field mapping

Some objects may have more than one information fields 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:
  1. Select the Object entity in Clarizen as explained above
  2. Open the Field Mapping section by clicking the + sign 
    The Field Mapping editor expands
  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 entity defined
  5. Select Clarizen's field name from the list
    The list is automatically filtered based on the entity defined
  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  to define additional fields
  8. Repeat steps 3-7 for all of the relevant fields associated with the defined object

 

 

 

Additional Mapping options

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, as an example this can be used to link a newly created project to the relevant customer.

To create Clarizen links:
  1. Select the Object entity in Clarizen as explained above
  2. Open the Create Clarizen Links section by clicking the + sign 
  3. Click  
    The Link editor expands
  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  to define additional links
  8. Repeat steps 4-6 for all of the desired 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. Open the Map Related Clarizen Objects section by clicking the + sign
  3. Click 
    The Relation editor expands
  4. Define the Related object
  5. Define the Relationship type
  6. To use conditions:
    • Click  
    • Define the desired condition
    • Repeat for multiple conditions
      When using multiple conditions, you can define the logical expression as either AND (default), or OR. Type OR to change the default logical expression
  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  to create additional relation mapping
  9. Repeat steps 4-7 for each of the relations

 

Synchronization fields mapping

You have the option to define fields in both Clarizen and the integration system for the purpose of monitoring your sync process.

If sync monitoring on the object ir 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

 

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 edit an existing trigger:
  1. Click Disable adjacent to the relevant trigger in order 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)
    The event trigger editor window opens
  4. Make the desired changes
  5. Click  to save the changes and close the editor

 

To create a new trigger:
  1. Click the  button located under the Event trigger list to create a new trigger
    The Event editor opens
  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  to complete the process 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.

Note:

Social syncs are performed every 10 minutes provided that the integrated application has a corresponding accessible API and that the social sync mapping was activated.

 

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

Click  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

Note:

You may notice that some hours in the list are grayed out, this means that these times are already used by existing scheduled workflow rules in your Clarizen account(s) and cannot be selected.

 

 

Sync logs

The Logs tab displays a log of all the trigger sync status 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 synchronization
  • 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 button - click the Refresh button 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 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 ststus related information

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 objects have 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 that 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.
NoteThe Other Email input box accepts semi-colon separated values.

Sync Registry

The Sync Registry tab allows you to see a complete list of all the object mapping available in the integration

The sync registry toolbar includes the following options:

  • Clarizen Organization name - allows you to select the relevant Clarizen Organization, specifically for integrations allowing multiple organization synchronization
  • System selector - filters the data based on mapping in Clarizen or the integrated system 
  • Item type filter - allows you to filter the information shown based on item type
  • Specific Search capabilities based on the map name and / or Identifier   

 

The sync registry data table includes several information and action columns, including:

  • Pending retry Icon  - indicates pending synchronization processes, clicking the icon initiates an immediate sync attempt
  • Action - allows you to quickly remove object mappings from the sync proces 
  • Last sync Date
  • Sync Status
  • Clarizen Item Type, Identifier, and Name  - object names may be hyperlinked in order to allow you to access the actual Clarizen object
  • Integrated system's Item Type, Identifier, and Name

 

 

Settings

The Setting tab includes advanced options including the ability to refresh the integration metadata and to disable the entire synchronization process

Click the Refresh metadata button to refresh the data structures and fields of the integrated system and Clarizen. The metadata includes the structure and fields of both the integrated system and Clarizen and is used so that the two systems are acquainted with one another.

After refreshing the metadata, a check-mark appears on the button indicating that the metadata has been refreshed 

 

Click the Disable entire sync button to stop the entire sync process.

Have more questions? Submit a request

Comments

Powered by Zendesk