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. | [ {
"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 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 {
"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 {
"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 {
"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.html | dd-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:
| true |
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 Small | Logo 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 Uploaded | Provides the logo upload status. | |
| Icon Uploaded | Provides 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. | |