Universal Adapter Descriptor

This page describes the fields that you'll configure and the values you'll provide for creating a UniversalAdapter. Many of the fields are common between the two types of Universal Adapter. This information may be helpful whether you are creating a Universal Adapter via the GUI or by directly editing an exported "descriptor" file.

Field Name

Description

Example

Application Type (type)
This is a mandatory field, as this field provides the application type.
Enter the same application name as is in the Universal Adapter license. This ‘type’ is what you chose to call your application for the purposes of integrating with ConnectALL. This is the application name your company provided in order for the Universal Adapter license to be created. The name has to be specified 'as is' without any spaces.
Once this Universal Adapter is associated with a license, the type can no longer be edited.
AcmeBespokeTicketingSystem
displayName
Enter the name of the adapter as you want it to be displayed in the ConnectALL UI. You'll use this name when mapping apps (when creating app-links). This is a mandatory field.Acme Bespoke Ticketing System
apiProvider
The Origin or the name of the API provider is mentioned here. Enter ‘ConnectALL’ or ‘ExternalApplication’. This is a mandatory field.
loginOptions
Contains additional login options, if any. If you are using any additional login options (apart from Username and Password) for validation by the application, enter those options. This is used for ExternalApplication as apiProvider only; it is not needed for ConnectALL as apiProvider. Any name you provide here will be available as a data entry field in the Entity Mapping configuration page – a place for you to enter the actual key or token later. Examples: PAT (used in TFS), APIKey, token. Depending on the options you provide here, those options will be passed as a part of the header or URL in the external application provider. You can send these details as a part of the header or query params. This is decided based on the options you choose in the configuration page. This is an optional field.If you are using a unique key or an APIKey, enter ”Key”(or)“apiKey”. More examples will include, client ID, client secrets, security tokens and additional connection options that will be used to authenticate an app.

Note: an array is expected even if there is only one value: [ "key" ]
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. Given the example to the right, you will see a 'project' and an 'issuetype' field in the Entity Mapping tab. The project dropdown will have two items (Test Project and Dev Project), and the issueType dropdown will have only one value (Bug).

You might want multiple app-links for your Universal Adapter, one app-link for each entity type or for each project.

The values attribute in the metadata configuration is mandatory. At least one value must be provided. Each value has an id and name pair. The name will be visible in the ConnectALL UI, and the id is used when communicating with the application. All the values you provide in the metadata become items in a drop-down list in the Entity Mapping tab. Adding multiple values allows you to select a particular value in each app-link that uses this adapter.

Using the example text, in the UI you will see 2 fields: project and issuetype. The project drop down will have the values Test Project and Dev Project. But when we communicate with the application over ReST, we’ll use the ids TP and/or DP (depending on which you select in the UI). This allows you to define one adapter that can talk to multiple projects or sync multiple entity types.

There is a relationship between what is entered in the metadata, projectFieldName and artifactFieldName. For ConnectALL to find out the project and IssueTypefield name, you have to provide the project field name and artifact field name.

[ {
  "name": "project",
  "values": [
      {
      "id": "TP",
      "name": "Test Project"
      },
      {
      "id": "DP",
      "name": "Dev Project"
      } 
  ]
}, {
  "name": "issuetype",
  "values": [
      {"id": "10001",
      "name": "Bug"
      }
  ]
 } ]
projectFieldName (Project Field)
Enter the name of the project field in your application, if applicable. This is an OPTIONAL entry and often only needs to be provided in order to access the project name from a Business Rule. If provided, ensure that the name that you enter here matches the name in your metadata.Project
artifactFieldName (Issue Type Field)
Many systems use the terms like records, items, objects, entities, tickets, or requests to describe the things that it stores. JIRA, for example, stores “issues”, VersionOne stores “assets”, and Trello stores “objects”. Whatever they are, they usually have multiple types of those things. For example, JIRA's issues might be Bugs or Stories, VersionOne has Backlog Items and Portfolio Items, and Trello has cards. In the artifactFieldName, enter the field in your application that holds its object's type.

This is a MANDATORY field and is used in synchronization. If project/issue type (Metadata) is available, provide it in the appropriate field. Another situation in which you might want to provide this is if you want access to the issue type in a Business Rule Script.
If you provide a value, it must match the name you provided in your metadata.
issueType
assetType
fields
The fields (data elements) to be displayed in the application link configuration's Field Mapping. A field is an object with id, name, value and data attributes. ID is the unique name of the field, which will be sent in the request payloads, name is the display name of the field, and data type depends on what an adapter will accept. Take the 'rich text fields' as an example. For this, ConnectALL expects a datatype. It could be wiki, HTML, Paragraph, String or PlainText. So if the field is Date, the datatype has to be configured as date. If it is DateTime, DateTime has to be provided. Specifying a data type here is optional, and helps you to map string fields.

Given the example to the right, in Field Mapping, you will see id, summary, status, and description fields. The status dropdown will have two items (TO DO and Open). When communicating with the end-application through ReST, ConnectALL will use the value '1' for TO DO and '2' for Open.

The values attribute in the fields configuration is optional. If provided, the values populate a dropdown in the Field Mapping UI. These values will be available in the the value mapping for field configuration. If provided, each value must have an id and name pair. The name is visible in the ConnectALL UI, and the id is what is used when communicating with the application. 
[ {
     "id": "id",
    "name": "Id",
    "datatype": "string"
  },
  {
     "id": "attachment",
    "name": "attachment",
    "datatype": "array"
  },
  {
    "id": "summary",
    "name": "Summary",
    "datatype": "string"
  },
  {
    "id": "status",
    "name": "Status",
    "datatype": "string",
    "values": [
       {
         "id": "1",
         "name": "TO DO"
       },{
         "id": "2",
         "name": "Open"
       }
     ]
  },
  {
    "id": "description",
    "name": "Description",
    "datatype": "string"
} ][ 
idFieldName (ID Field)

Provide the name of the record ID field in your application. The ID is the unique identifier of your application's entities. If provided, this value must match a field in the fields attribute.

For an External Application Provided API style Universal Adapter, a value must be provided.

For a ConnectALL Provided API style Universal Adapter, this is optional. If provided, you may use this field name instead of "id" in your postRecord call. This is a mandatory field.

record_id
key
Id
titleFieldName (Title Field)
Provide the field name of your application’s title field. This is a mandatory field. Most applications have a mandatory title field. This value must match a field in the fields attribute. Summary, Name, Short_Description, Title, etc.‘Summary’ is a mandatory title field in JIRA. In Doors NG it is Object_Text.
changedDateFieldName (Modified Date Field)
Enter the name of your modified or changed date field. This needs to be the field that corresponds to the last modified timestamp on the entity. ConnectALL needs this information for synchronization. This is the field ConnectALL will use to find out the modified time of an issue. The name you specify here must match with one of the fields that you provided in the fields list. This is a mandatory field. For example, Jira field - Updated, QC- Modified Time.

modified
changed
changedate

{ 
   "id": "changedate", 
   "name": "changedate", 
   "datatype": "date" 
}
attachmentFieldName

Name of the attachment field. This field detail is expected by ConnectALL to identify the type of attachment synchronization. We have 2 types of Attachment synchronization – Physical Attachment Synchronization and Attachment as an URL. Based on the fields mapped on the source and destination application, ConnectALL decides which synchronization has to be done. The Datatype value has to be in the lower case. This is an optional field.

This is only used by an ConnectALL Provided API style Universal Adapter.

file
attachment

{
    "id": "attachmentFieldName",
    "name": "attachmentFieldName",
    "datatype": "string"
}
attachmentFieldId

Id of the attachment field. This field detail is expected by ConnectALL to identify the type of attachment synchronization. We have 2 types of Attachment synchronization – Physical Attachment Synchronization and Attachment as an URL. Based on the fields mapped on the source and destination application, ConnectALL decides which synchronization has to be done. The Datatype value has to be in the lower case. This is an optional field. 

This is only used by an ConnectALL Provided API style Universal Adapter.

file
attachment

{
    "id": "attachmnetFieldid",
    "name": "attachmentFieldid",
    "datatype": "string"
}
isISO8601DateFormat
The information regarding the date time format is provided in this field. If your application returns the date fields of your entity in this format (ISO8601), set it to 'True', else set to 'False'. This is an optional field. For the configured date fields, if you have enabled this property, the formatting will be done.
This value is related to dateFormat, dateTimeFormat, and queryDateFormat.
Note that this is not a mandatory field but if you don't specify, by default, it will be false.
true
false
dateFormat
The date format that ConnectALL should use when sending dates TO your application. (Conversely, the date formats in an app-link's advanced properties is the format that ConnectALL is expecting the application to send TO ConnectALL.) This is a mandatory field. For more information, refer to this page: https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.htmldd-MM-yyyy
yyyy/MM/dd
dateTimeFormat

The Date-Time Format that ConnectALL should use when sending date-time information TO your application. (Conversely, the date formats in an app-link's advanced properties is the format that ConnectALL is expecting the application to send TO ConnectALL.) If you are configuring date and time fields, this is mandatory. Note that the date and time fields are needed for ConnectALL to synchronize. This is a mandatory field.

dd-MM-yyyy HH:mm:ss.SSS
queryDateFormat
For some applications, the date formats used to retrieve the modified records differ from the date formats returned in the response from the application. Therefore, use queryDateFormat field to specify the format to use in the query. This is a mandatory field. Starting from version 2.10.24, ConnectALL provides the option to select a Unix Epoch format (can be ‘Millis’ or ‘Seconds’) for date format. Read the information here to know about the query date formats we support.yyyy/MM/dd

Pagination Supported?

This is applicable only when the ExternalApplication is the API Provider. Hence this is not a mandatory field. Some applications like Zephyr and Sonarqube return paginated results when querying for the modified records. To enter a value against the Pagination Supported? field:

  • Click the pencil icon on the top right side corner of the adapter properties list to edit the configuration.
  • Enter “true” against the Pagination Supported? field if your External Application paginates results.
  • Click the checkmark icon on the top right side corner of the adapter properties list to save the descriptor changes. You'll see the Pagination Attributes property displayed in the list with a View link against it.
  • Click the pencil icon again on the top right side corner of the adapter properties list.
  • Click the Configure link against the Pagination Attributes property. The Artifact Edit screen displays three attributes by default – Page SizeTotal Modified Records and Offset. You can enter the desired values for the listed attributes or add new attributes and enter the values.
  • Click Save in the Artifact Edit screen.
  • Click the checkmark icon on the top right side corner of the adapter properties list to save the changes to the configuration. The message, ‘Adapter descriptor Updated successfully’ confirms the changes.

true
false

urlDescription

Help text that will be displayed below the Url field in the configuration page. This would be helpful for the user on url format. This is used for ExternalApplication as apiProvider only; it is not needed for ConnectALL as apiProvider. Hence, this is not a mandatory field. 


userNameDescription

Help text that will be displayed below the UserName field in the configuration page. This is used for ExternalApplication as apiProvider only; it is not needed for ConnectALL as apiProvider. Hence, this is not a mandatory field.


passwordDescription

Help text that will be displayed below the Password field in the configuration page. This is used for ExternalApplication as apiProvider only; it is not needed for ConnectALL as apiProvider. Hence, this is not a mandatory field.


apiVersion
The version of the ConnectALL API. For now, the version is '1'. However, in the future enhancements, this could be changed. If it changes, you will be able to change it based on your requirement. This is not a mandatory field.
commentFieldName

Name of the comment field. This is required if you need to synchronize the comments field and if you are using ConnectALL as API Provider. This is available from version 2.10.3.


commentFieldId
ID of the Comment field. This is available from version 2.10.3.
testStepsFieldName
This field is not supported yet.

Logo

Application logo to be displayed in the Application selection drop-down list while configuring an app-link. 
Logo SmallLogo displayed in the application window while configuring an app-link. This is the logo that will be used in the value stream visuallization layout. The size requirements for a small logo is 20*20; but if it is not in the required size, ConnectALL adjusts the size of an image to suit the requirements.
Logo UploadedProvides the logo upload status.
Icon UploadedProvides the icon upload status.
Note: ConnectALL validates the file name of the images during upload. You have to provide the correct name of the image as you will not be able to upload the image if you provide the wrong name. Also, if you change the name of the image after uploading it, the image will not be displayed. It is sufficient if you provide the image name and not the entire file path. 
Transformation Spec

This is for the External Application API provider to configure the transformation specification for the operations such as GET_MODIFIED_RECORDS, GET_RECORD_BY_ID, CREATE_RECORD,UPDATE_RECORD. If the transformations scripts are not configured for an External Application Provider API, it will result in synchronization issues.