Create and Edit


Before You Start

Before you start, check if the application has a ReST API if you are using an external application provided API.

Creating a Universal Adapter

You can create a universal adapter through the ConnectALL UI. To do this:

  1. Click the cogwheel icon on the top right corner of the navigation bar and click Universal Adapters from the drop-down menu.
  2. Click Create Adapter. The Create New Adapter screen will be displayed.
  3. Enter a name, application type, and select an API Provider (from the drop-down list). Note that the application type you enter here should be the same value that is in your license.
  4. Click Proceed. The screen displays all the fields that you need to configure in an adapter.
  5. Click against the fields to enter the values. For the MetaData field, click Configure and enter the details (datatype) in the Artifact Edit dialog box.

    In the version 2.10.9 and above:

    • A datatype drop-down list is displayed in the Artifact Edit dialog box, from which you can choose a datatype.
    • For the ID, Title, and Modified Date Fields, you will be able to add the fields directly. To do so, click against a field, enter the field name and click Add to Fields. The datatype of those fields will be automatically displayed in the Artifact Edit window. 
  6. Click Save Configuration. You will be able to save only if you have finished configuring the mandatory fields (displayed in red).

Once you save, the Universal Adapters page will be displayed and it will display the adapter that you have created. You could click the  icon against Active to activate the adapter you created.


Notes
  • When you create a Universal adapter, the Query Date Format is one of the fields in which you have to choose a date format. The option that is selected here will be the format that is supported by that application for which you are creating the Universal Adapter. Some adapters accept only the Unix Epoch format. To support such adapters, starting from version 2.10.24, ConnectALL provides the option to select a Unix Epoch format (can be ‘Millis’ or ‘Seconds’) for date format. The Unix Epoch format that your application supports can be chosen from the drop-down list options as shown below. By default, the DATE_TIME_FORMAT option is selected. If your adapter supports only Unix Epoch timestamp format, please choose either MILLIS_SINCE_UNIX_EPOCH or SECS_SINCE_UNIX_EPOCH depending on what your application supports. If your application supports only the DATE_TIME_FORMAT, and not a Unix Epoch format, select the option DATE_TIME_FORMAT and enter the date and time in the adjacent field that will appear. For example, if you are creating a Universal Adapter for Jira that supports only the DATE_TIME_FORMAT, do not choose the displayed Unix Epoch formats. If you choose an option different from the one that is supported by the application, it will not be possible for ConnectALL to read the records from Jira, and that will result in synchronization errors.

  • Metadata – This is Metadata for the application. Eg: Project, Issue type etc. Metadata is mandatory and the values attribute in the metadata configuration is also mandatory. Specify Metadata for the application. Project and Issue Type (Entity Type) are the two main pieces of metadata that many applications need. This is the info that you will see in the Entity Mapping tab.
  • Fields – The fields (data elements) to be displayed in the application link's Field Mapping section.
  • Id Field – Provide the name of the record ID field in your application.
  • Title Field – Provide the field name of your application’s title field (For example, Summary, Name, Short_Description, Title, etc).
  • Logo and Icon uploaded fields provides the upload status of logo and icon.

Check this page for more information on fields.  

Editing an Adapter Descriptor 

  1. Click  on the adapter descriptor (top right corner) to enable the edit mode.
  2. Once the edit icon is clicked, the adapter will be in edit mode with the save and cancel icons in the upper right corner.



  3. Click on any of the properties to edit the configuration.
  4. To edit the values for the fields like metadata, fields, and login option, click on the configure link, and edit the values from the popup.
  5. Once all the values are configured, click  to save the configuration.

Connection Configuration

  1. In ConnectALL's UI, under Connections, add a connection to your end application. 
  2. Specify the application type, which is the application name you specified when you created your Universal Adapter.
  3. Give the connection a name, specify the URL of the application, and any necessary credentials.
  4. Select the supported authentication types. If you choose:
    1. Basic – The credentials provided in the configuration screen will be used.
    2. API Key – When the API Key auth type is selected, the option to provide the API key name and the value will be displayed. 
  5. Select the 'Auth' option. If you choose:
    1. Header – The authentication details will be sent in the header.
    2. URL – The authentication details will be sent in the URL. Click here for more information. In addition, you can provide these details in the Connections screen. To do this, click Connections in the top navigation bar, and in the Connections screen, click the pencil icon against the required connection to edit.

Create Application Link

The application link can be configured similarly to the other adapters. Please find the reference in Setup (Map Applications). The metadata and fields will be loaded from the adapter descriptor that you uploaded.

API Authentication

ConnectALL uses the API KEY authentication for synchronization.

Generate an API Key

A ConnectALL system admin or a Group admin is the only user who can generate an API Key.  Note that a non-admin user cannot generate an API Key.  The API Key management feature is available in the 'User Management' page of ConnectALL UI from where you can generate an API Key.

  • In the above screen, click Generate to generate an API Key. You can copy the displayed key.
  • After you generate the key, View and Deactivate buttons appear replacing the Generate button. You can view the generated key or if required, deactivate it.

Multi-Project Configuration

Starting from 2.10.29.1, you can use the Multi-Project configuration feature in the universal adapter. Enabling the universal adapter for multi-project configuration is done in the adapter descriptor screen when you create the adapter. Let’s see how it is done. 

Procedure

Follow steps 1-4 provided in the ‘Creating a Universal Adapter’ section. When you complete it, the screen displays all the fields that you need to configure in an adapter. When you are filling out all the required fields,

  1. Click the Multi Project Supported? field to select it. The Project Based Login? Field will be displayed.

     

    Only if you enable the Multi Project Supported? field, 
    1. The Project Based Login? field (above image) will appear. Also,
    2. The ALL option in the project drop-down list in the Entity Mapping screen will be displayed. 


      Note: The Template Project field is not available as the fields are configured as a part of the descriptor. 

  2. Click the Project Based Login? field only if your application requires a project-based login’. (The Project Based Login? field helps applications that do not have APIs to query the list of projects by querying each project.)

The rest of the configuration details can be specified when you configure the API. To configure,

  1. Click on Configure against the Api Configuration option. 



  2. The following screen will be displayed. click the Configuration icon (against the operation and select the mappedprojects option. This is to add the mapped projects to the URL. (The mappedprojects option in the configuration menu will appear only if you have not chosen the ‘Project based login?’ option. This option is useful in scenarios where the mapped projects in the application link needs to be passed only through the URL as project based login is not available; In such a situation, the mapped projects gets included as a part of the URL.) 



  3. When you click the mappedprojects option, check the QUERY MODIFIED RECORDS field. It will appear as shown in the above image.

    Info

    The $mappedProjects attribute appears in the QUERY MODIFIED RECORDS field once you click the mappedprojects option and it is introduced to pass the multiple projects configured in an application link. Note that if you have chosen the Project Based Login? field, it is not required to pass all the projects, and in that case, the mappedprojects option will not be available. On the other hand, if you have not chosen Project Based Login?, the mapped projects option will be available. The QUERY MODIFIED RECORDS contains the following attributes as below:

    /rest/api/2/search${mappedprojects[ValueEnclosingChar:(')] [ValueSeparator:(,)]}

    If you have a project ID that has to be enclosed along with the value separators for the projects, include them as a part of [ValueEnclosingChar:(')] [ValueSeparator:(,)] attributes respectively.

  4. Click Save as draft or Activate as required to proceed. 

The above procedure was for the GET method. Let's see what happens when you choose POST. When you choose POST and click on Request Spec Config, the below screen will be displayed. 


         

In the Transformation Spec column,  you can write a spec including the list of projects in the required format. To know more about Transformation Spec, click here.

  • When mapping an Insights adapter, you will be mapping two ‘project’ Fields.



  • When value mapping the ‘project’ field, in a normal scenario you will be expected to fill in the values in the value mapping field in both the applications, when you are mapping an Insights Adapter that is a write-only adapter, you can leave the field empty.

Synchronizing Comments and Attachments

Starting from version 2.10.32, the Universal Adapter allows you to synchronize comments and attachments when using it. Enabling the universal adapter to sync comments and attachments is done in the adapter descriptor screen when you create or modify the adapter. Let’s see how it's done.  

Procedure

  1. Follow steps 1-4 in theCreating a Universal Adaptersection. When you complete it, the screen displays all the fields that you need to configure.
  2. Click the Sync Comments? and Sync Attachments? options.

     

    Note that, when you choose Sync Comments? and Sync Attachments? options or any one of them, depending upon your selection, the related APIs get added to the API Configuration screen that you need to configure. This is discussed in the Configure the APIs section further below.

  3. Click Configure displayed against the Fields option. The Artifact Edit screen displays all the fields ID, Name, and Datatype that you can select. Select the DATATYPE.



  4. Click Save

Configuring the APIs

The rest of the configuration details can be specified when you configure the API. To configure,

  1. Click on Configure against the Api Configuration option. The below screen will be displayed. 


    *In the above image, the APIs will be displayed depending on the option(s) you've chosen in step 2 of the previous procedure.
  2. Click the configuration icon (against an API and select the required URL option from the drop-down menu. Note that, the URL options displayed for each of the APIs are different.
  3. Make the necessary modifications to the APIs.
  4. Click Save as draft or Activate as required to proceed. 

The above procedure was for the GET method. Let's see what happens when you choose POST for an API. For example, Let's look at the operations of the RETRIEVE COMMENTS and SAVE COMMENTS APIs when you choose the POST option against them. The Request Spec Config option will be available to click after you choose the POST option and the following screen will be displayed when you click on Request Spec Config. The highlighted parts in the below images are the requests. In the Transformation Spec column,  you can write a spec including the list of projects in the required format. To know more about Transformation Spec, click here.

               
                                                                                         Retrieve Comments

               
                                                                                         Save Comments

Time Difference Configuration

To know how to calculate the time difference, and configure it in the ConnectALL UI, read the topic Time Difference Configuration.