"openapi: 3.1.0\ninfo:\n title: Tool Connector API\n description: |\n API for managing tool connector integrations with third-party tools in Polaris.\n contact:\n name: Black Duck Software, Inc.\n url: https://polaris.blackduck.com\n version: 1.0.0\ntags:\n - name: Connection CRUD\n description: Endpoints for managing connections to external tools.\n - name: Connection Validation\n description: Endpoints for validating connection properties.\n - name: Connection Mappings\n description: Endpoints for managing mappings between Polaris projects/branches and external tool projects/versions.\n - name: Connection Sync\n description: Endpoints for triggering and monitoring synchronization of data from external tools.\nservers:\n - url: https://polaris.blackduck.com\n description: Polaris API server\nsecurity:\n - ApiKeyAuth: []\npaths:\n /api/integrations/tool-connectors/connections/{connectionId}:\n get:\n operationId: getConnection\n summary: Get connection by ID\n description: |\n Get a connection based on its UUID identifier.\n tags:\n - Connection CRUD\n parameters:\n - name: connectionId\n in: path\n required: true\n description: The unique identifier of the connection.\n schema:\n type: string\n format: uuid\n example: 0197c6b5-571a-79e0-9412-8d7b09b91b51\n responses:\n '200':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/post/responses/201'\n '401':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/401'\n '403':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/403'\n '404':\n description: Not found.\n content:\n application/problem+json:\n schema:\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/401/content/application~1problem%2Bjson/schema'\n example:\n type: urn:x-integrations-service:Not-Found\n title: Not found\n status: 404\n detail: Requested resource is not found.\n patch:\n operationId: updateConnection\n summary: Update connection\n description: |\n Update an existing connection. Only the fields provided in the request body will be updated.\n tags:\n - Connection CRUD\n parameters:\n - $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D/get/parameters/0'\n requestBody:\n required: true\n content:\n application/vnd.polaris.integrations.tims.connection-1+json;charset=UTF-8:\n schema:\n type: object\n description: Object used to update an existing connection.\n properties:\n name:\n type: string\n description: User-provided name for the connection.\n applicationPrefix:\n type: string\n description: Prefix used when creating Applications to contain Projects during the \"Project Sync\" process.\n enabled:\n type: boolean\n description: Whether the connection is enabled.\n properties:\n type: object\n description: Connection properties specific to the integration type.\n additionalProperties: true\n example:\n server_url: https://example.blackduck.com/sca\n api_key: mysupersecretapitoken\n example:\n name: My updated connection\n applicationPrefix: BD\n enabled: true\n properties:\n server_url: https://example.blackduck.com/sca\n api_key: mysupersecretapitoken\n example:\n name: My updated connection\n applicationPrefix: BD\n enabled: true\n properties:\n server_url: https://example.blackduck.com/sca\n api_key: mysupersecretapitoken\n responses:\n '200':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/post/responses/201'\n '400':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/post/responses/400'\n '401':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/401'\n '403':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/403'\n '404':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D/get/responses/404'\n delete:\n operationId: deleteConnection\n summary: Delete connection\n description: |\n Delete a connection. If cascade=true, all associated mappings will also be deleted.\n tags:\n - Connection CRUD\n parameters:\n - $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D/get/parameters/0'\n - name: cascade\n in: query\n required: false\n description: Whether to delete all associated mappings.\n schema:\n type: boolean\n default: false\n example: true\n responses:\n '202':\n description: Connection deletion accepted.\n '401':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/401'\n '403':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/403'\n '404':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D/get/responses/404'\n /api/integrations/tool-connectors/connections:\n get:\n operationId: listConnections\n summary: List connections\n description: |\n List all connections with pagination and filtering options.\n tags:\n - Connection CRUD\n parameters:\n - name: integrationId\n in: query\n required: false\n description: Filter connections by integration ID. For Black Duck SCA, the value is 8481683c-cdbe-4e6b-88ad-a1d2fe4abe5d.\n schema:\n type: string\n format: uuid\n example: 8481683c-cdbe-4e6b-88ad-a1d2fe4abe5d\n - name: _filter\n in: query\n description: >-\n A filter string that further limits the results returned, expressed in the [rsql](https://github.com/jirutka/rsql-parser) format. The filter supports `name`, `enabled`, `connectionId`,\n `applicationPrefix`, `createdAt`, and `updatedAt`.\n schema:\n type: string\n format: rsql\n example: name==Black Duck;enabled==true\n - name: _offset\n in: query\n required: false\n description: Index offset for page.\n schema:\n type: integer\n default: 0\n example: 20\n - name: _limit\n in: query\n required: false\n description: Items per page.\n schema:\n type: integer\n default: 20\n maximum: 100\n example: 50\n - name: _sort\n in: query\n required: false\n description: Field to sort by.\n schema:\n type: string\n enum:\n - name\n - enabled\n - lastSynced\n default: name\n example: name\n - name: _order\n in: query\n required: false\n description: Sort order.\n schema:\n type: string\n enum:\n - asc\n - desc\n default: asc\n example: asc\n responses:\n '200':\n description: A collection of connections.\n content:\n application/vnd.polaris.integrations.tims.connection-1+json;charset=UTF-8:\n schema:\n type: object\n description: A collection of connection objects with pagination information.\n required:\n - _items\n - _collection\n - _links\n properties:\n _items:\n type: array\n description: Array of connection objects in the collection.\n items:\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/post/responses/201/content/application~1vnd.polaris.integrations.tims.connection-1%2Bjson%3Bcharset%3DUTF-8/schema'\n _collection:\n type: object\n description: Metadata about the collection including pagination information.\n properties:\n itemCount:\n type: integer\n description: Total number of items in the collection.\n currentPage:\n type: integer\n description: The current page number of the results (one-based).\n pageCount:\n type: integer\n description: Total number of pages.\n _type:\n type: string\n description: Type identifier for the collection.\n _links:\n type: array\n description: Array of link objects for navigation.\n items:\n $ref: >-\n #/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D~1mappings~1search/post/responses/200/content/application~1vnd.polaris.integrations.tims.connection-branch-mapping-1%2Bjson%3Bcharset%3DUTF-8/schema/properties/_links/items\n example:\n _items:\n - id: 0197c6b5-571a-79e0-9412-8d7b09b91b51\n name: Black Duck Production\n description: Connection to our production Black Duck instance\n applicationPrefix: BD\n enabled: true\n createdAt: '2025-01-15T14:30:00Z'\n updatedAt: '2025-01-15T14:30:00Z'\n syncState:\n status: COMPLETE\n startedAt: '2025-01-15T14:30:00Z'\n finishedAt: '2025-01-15T14:35:00Z'\n lastSuccess: '2025-01-15T14:35:00Z'\n integration:\n id: 8481683c-cdbe-4e6b-88ad-a1d2fe4abe5d\n name: Black Duck SCA\n properties:\n server_url: https://example.blackduck.com/sca\n api_key:\n saved: true\n _collection:\n itemCount: 1\n currentPage: 1\n pageCount: 1\n _type: integration-connections\n _links:\n - href: /api/integrations/tool-connectors/connections?_offset=0&_limit=20\n rel: self\n method: GET\n example:\n _items:\n - id: 0197c6b5-571a-79e0-9412-8d7b09b91b51\n name: My connection\n description: This is a tool connection.\n applicationPrefix: BD\n enabled: true\n createdAt: '2024-01-15T10:30:00Z'\n updatedAt: '2024-01-15T14:45:00Z'\n syncState:\n status: COMPLETE\n startedAt: '2024-01-15T14:00:00Z'\n finishedAt: '2024-01-15T14:45:00Z'\n lastSuccess: '2024-01-15T14:45:00Z'\n integration:\n id: 8481683c-cdbe-4e6b-88ad-a1d2fe4abe5d\n name: Black Duck SCA\n properties:\n server_url: https://example.blackduck.com/sca\n api_key:\n saved: true\n _collection:\n itemCount: 1\n currentPage: 1\n pageCount: 1\n _type: integration-connections\n _links:\n - href: https://polaris.blackduck.com/api/integrations/tool-connectors/connections?_offset=0&_limit=20\n rel: self\n method: GET\n - href: https://polaris.blackduck.com/api/integrations/tool-connectors/connections?_offset=0&_limit=20\n rel: first\n method: GET\n '401':\n description: User is not authorized.\n content:\n application/problem+json:\n schema:\n type: object\n description: Standard error response format for Polaris APIs.\n properties:\n type:\n type: string\n description: The type of the error produced. Typically, a uniform resource name (URN).\n title:\n type: string\n description: The title for the error.\n status:\n type: integer\n format: int64\n description: The status code for the error.\n detail:\n type: string\n description: A detailed description of the error.\n example: Request cannot be processed, as the passed request payload is not recognised.\n example:\n type: urn:x-integrations-service:bad-request\n title: Bad Request\n status: 400\n detail: Request cannot be processed, as the passed request payload is not recognised.\n example:\n type: urn:x-integrations-service:Unauthorized\n title: Unauthorized\n status: 401\n detail: Operation is not permitted.\n '403':\n description: Forbidden.\n content:\n application/problem+json:\n schema:\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/401/content/application~1problem%2Bjson/schema'\n example:\n type: urn:x-integrations-service:Forbidden\n title: Forbidden\n status: 403\n detail: Access denied, cannot access the requested resource.\n post:\n operationId: createConnection\n summary: Create connection\n description: |\n Create a new connection.\n tags:\n - Connection CRUD\n requestBody:\n required: true\n content:\n application/vnd.polaris.integrations.tims.connection-1+json;charset=UTF-8:\n schema:\n type: object\n description: Represents a connection to an external tool or service.\n required:\n - name\n - integrationId\n - properties\n properties:\n id:\n type: string\n format: uuid\n description: Unique connection identifier.\n readOnly: true\n name:\n type: string\n description: User-provided name for the connection.\n example: My connection\n description:\n type: string\n description: User-provided description for the connection.\n maxLength: 1024\n example: This is a tool connection.\n applicationPrefix:\n type: string\n description: Prefix used when creating Applications to contain Projects during the \"Project Sync\" process.\n example: BD\n enabled:\n type: boolean\n description: Whether the connection is enabled.\n default: true\n integrationId:\n type: string\n format: uuid\n description: UUID of the integration type. For Black Duck SCA, the value is 8481683c-cdbe-4e6b-88ad-a1d2fe4abe5d.\n properties:\n type: object\n description: Connection properties specific to the integration type.\n additionalProperties: true\n example:\n server_url: https://example.blackduck.com/sca\n api_key: mysupersecretapitoken\n createdAt:\n type: string\n format: date-time\n description: The time that this connection was created.\n readOnly: true\n updatedAt:\n type: string\n format: date-time\n description: The time that this connection was most recently updated.\n readOnly: true\n syncState:\n $ref: >-\n #/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D~1sync-data~1status/get/responses/200/content/application~1vnd.polaris.integrations.tims.connection-sync-status-1%2Bjson%3Bcharset%3DUTF-8/schema\n integration:\n $ref: >-\n #/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D~1project-mappings/get/responses/200/content/application~1vnd.polaris.integrations.tims.connection-project-mapping-1%2Bjson%3Bcharset%3DUTF-8/schema/properties/_items/items/properties/integration\n example:\n id: 0197c6b5-571a-79e0-9412-8d7b09b91b51\n name: Black Duck Production\n description: Connection to our production Black Duck instance\n applicationPrefix: BD\n enabled: true\n integrationId: 8481683c-cdbe-4e6b-88ad-a1d2fe4abe5d\n properties:\n server_url: https://example.blackduck.com/sca\n api_key: mysupersecretapitoken\n createdAt: '2025-01-15T14:30:00Z'\n updatedAt: '2025-01-15T14:30:00Z'\n syncState:\n status: COMPLETE\n startedAt: '2025-01-15T14:30:00Z'\n finishedAt: '2025-01-15T14:35:00Z'\n lastSuccess: '2025-01-15T14:35:00Z'\n integration:\n id: 8481683c-cdbe-4e6b-88ad-a1d2fe4abe5d\n name: Black Duck SCA\n example:\n name: My connection\n description: This is a tool connection.\n applicationPrefix: BD\n integrationId: 8481683c-cdbe-4e6b-88ad-a1d2fe4abe5d\n properties:\n server_url: https://example.blackduck.com/sca\n api_key: mysupersecretapitoken\n responses:\n '201':\n description: A single connection.\n content:\n application/vnd.polaris.integrations.tims.connection-1+json;charset=UTF-8:\n schema:\n type: object\n description: Response object representing a connection to an external tool or service.\n required:\n - id\n - name\n - enabled\n - createdAt\n - updatedAt\n - syncState\n - integration\n - properties\n properties:\n id:\n type: string\n format: uuid\n description: Unique connection identifier.\n name:\n type: string\n description: User-provided name for the connection.\n description:\n type: string\n description: User-provided description for the connection.\n maxLength: 1024\n example: This is a tool connection.\n applicationPrefix:\n type: string\n description: Prefix used when creating Applications to contain Projects during the \"Project Sync\" process.\n example: BD\n enabled:\n type: boolean\n description: Whether the connection is enabled.\n createdAt:\n type: string\n format: date-time\n description: The time that this connection was created.\n updatedAt:\n type: string\n format: date-time\n description: The time that this connection was most recently updated.\n syncState:\n $ref: >-\n #/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D~1sync-data~1status/get/responses/200/content/application~1vnd.polaris.integrations.tims.connection-sync-status-1%2Bjson%3Bcharset%3DUTF-8/schema\n integration:\n $ref: >-\n #/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D~1project-mappings/get/responses/200/content/application~1vnd.polaris.integrations.tims.connection-project-mapping-1%2Bjson%3Bcharset%3DUTF-8/schema/properties/_items/items/properties/integration\n properties:\n type: object\n description: Connection properties specific to the integration type. Secret fields will be replaced with a placeholder.\n additionalProperties: true\n example:\n server_url: https://example.blackduck.com/sca\n api_key:\n saved: true\n example:\n id: 0197c6b5-571a-79e0-9412-8d7b09b91b51\n name: Black Duck Production\n description: Connection to our production Black Duck instance\n applicationPrefix: BD\n enabled: true\n createdAt: '2025-01-15T14:30:00Z'\n updatedAt: '2025-01-15T14:30:00Z'\n syncState:\n status: COMPLETE\n startedAt: '2025-01-15T14:30:00Z'\n finishedAt: '2025-01-15T14:35:00Z'\n lastSuccess: '2025-01-15T14:35:00Z'\n integration:\n id: 8481683c-cdbe-4e6b-88ad-a1d2fe4abe5d\n name: Black Duck SCA\n properties:\n server_url: https://example.blackduck.com/sca\n api_key:\n saved: true\n example:\n id: 0197c6b5-571a-79e0-9412-8d7b09b91b51\n name: My connection\n description: This is a tool connection.\n applicationPrefix: BD\n enabled: true\n createdAt: '2024-01-15T10:30:00Z'\n updatedAt: '2024-01-15T14:45:00Z'\n syncState:\n status: COMPLETE\n startedAt: '2024-01-15T14:00:00Z'\n finishedAt: '2024-01-15T14:45:00Z'\n lastSuccess: '2024-01-15T14:45:00Z'\n integration:\n id: 8481683c-cdbe-4e6b-88ad-a1d2fe4abe5d\n name: Black Duck SCA\n properties:\n server_url: https://example.blackduck.com/sca\n api_key:\n saved: true\n '400':\n description: Bad request.\n content:\n application/problem+json:\n schema:\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/401/content/application~1problem%2Bjson/schema'\n example:\n type: urn:x-integrations-service:bad-request\n title: Bad Request\n status: 400\n detail: Request cannot be processed, as the passed request payload is not recognised.\n '401':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/401'\n '403':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/403'\n /api/integrations/tool-connectors/connections/validate-url:\n post:\n operationId: validateConnectionUrl\n summary: Validate connection URL\n description: |\n Validate a connection URL field. This endpoint checks if the URL is valid, reachable, and not suspicious.\n tags:\n - Connection Validation\n parameters:\n - $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/parameters/0'\n requestBody:\n required: true\n content:\n application/vnd.polaris.integrations.tims.connection-validation-payload-1+json;charset=UTF-8:\n schema:\n type: object\n required:\n - server_url\n properties:\n server_url:\n type: string\n description: The URL to validate.\n example:\n server_url: https://example.blackduck.com/sca\n responses:\n '200':\n description: URL validation result.\n content:\n application/vnd.polaris.integrations.tims.connection-validation-1+json;charset=UTF-8:\n schema:\n type: object\n description: Represents the result of a validation operation.\n required:\n - isValid\n properties:\n isValid:\n type: boolean\n description: Whether the validation passed successfully.\n feedback:\n type: array\n description: List of validation feedback items.\n items:\n type: object\n required:\n - field\n properties:\n field:\n type: string\n description: The field that the feedback relates to.\n checkmark:\n type: boolean\n description: Indicates a successful validation check.\n warning:\n type: string\n description: Warning message for the field.\n error:\n type: string\n description: Error message for the field.\n info:\n type: string\n description: Informational message for the field.\n example:\n isValid: true\n feedback:\n - field: server_url\n checkmark: true\n info: Successfully connected to https://example.blackduck.com/sca\n '400':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/post/responses/400'\n '401':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/401'\n '403':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/403'\n /api/integrations/tool-connectors/connections/validate-form:\n post:\n operationId: validateConnectionForm\n summary: Validate connection properties\n description: |\n Validate connection properties. This endpoint checks if the provided properties are valid for the specified integration.\n tags:\n - Connection Validation\n parameters:\n - $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/parameters/0'\n - name: connectionId\n in: query\n required: false\n description: The ID of an existing connection to update. If not provided, a new connection will be validated.\n schema:\n type: string\n format: uuid\n example: 550e8400-e29b-41d4-a716-446655440000\n requestBody:\n required: true\n content:\n application/vnd.polaris.integrations.tims.connection-validation-payload-1+json;charset=UTF-8:\n schema:\n type: object\n description: Connection properties specific to the integration type.\n additionalProperties: true\n example:\n server_url: https://example.blackduck.com/sca\n api_key: mysupersecretapitoken\n responses:\n '200':\n description: Form validation result.\n content:\n application/vnd.polaris.integrations.tims.connection-validation-1+json;charset=UTF-8:\n schema:\n $ref: >-\n #/paths/~1api~1integrations~1tool-connectors~1connections~1validate-url/post/responses/200/content/application~1vnd.polaris.integrations.tims.connection-validation-1%2Bjson%3Bcharset%3DUTF-8/schema\n example:\n isValid: true\n feedback:\n - field: server_url\n checkmark: true\n - field: api_key\n checkmark: true\n info: API key validated successfully\n '400':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/post/responses/400'\n '401':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/401'\n '403':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/403'\n /api/integrations/tool-connectors/connections/{connectionId}/sync-data:\n post:\n operationId: triggerProjectSync\n summary: Trigger project sync\n description: |\n Trigger a project sync for the specified connection. This will synchronize project data between Polaris and the external tool.\n If projectId or applicationId is provided, only the specified project or application will be synchronized.\n tags:\n - Connection Sync\n parameters:\n - $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D/get/parameters/0'\n - name: projectId\n in: query\n required: false\n description: The ID of a specific project to synchronize.\n schema:\n type: string\n format: uuid\n example: 550e8400-e29b-41d4-a716-446655440000\n - name: applicationId\n in: query\n required: false\n description: The ID of a specific application to synchronize.\n schema:\n type: string\n format: uuid\n example: 38a28c8c-6e32-4a71-9a8d-254d67f9073e\n responses:\n '201':\n description: Sync started successfully.\n content:\n application/vnd.polaris.integrations.tims.connection-sync-1+json;charset=UTF-8:\n schema:\n type: object\n required:\n - syncId\n properties:\n syncId:\n type: string\n format: uuid\n description: The ID of the sync job.\n example:\n syncId: 9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d\n '202':\n description: Sync already running.\n content:\n application/vnd.polaris.integrations.tims.connection-sync-1+json;charset=UTF-8:\n schema:\n type: object\n required:\n - syncId\n properties:\n syncId:\n type: string\n format: uuid\n description: The ID of the existing sync job.\n example: 20354d7a-e4fe-47af-8ff6-187bca92f3f9\n '400':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/post/responses/400'\n '401':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/401'\n '403':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/403'\n '404':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D/get/responses/404'\n /api/integrations/tool-connectors/connections/{connectionId}/sync-data/status:\n get:\n operationId: getProjectSyncStatus\n summary: Get project sync status\n description: |\n Get the status of a project sync job for the specified connection.\n If projectId or applicationId is provided, only the status for the specified project or application will be returned.\n tags:\n - Connection Sync\n parameters:\n - $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D/get/parameters/0'\n - name: projectId\n in: query\n required: false\n description: The ID of a specific project to get sync status for.\n schema:\n type: string\n format: uuid\n example: 550e8400-e29b-41d4-a716-446655440000\n - name: applicationId\n in: query\n required: false\n description: The ID of a specific application to get sync status for.\n schema:\n type: string\n format: uuid\n example: 38a28c8c-6e32-4a71-9a8d-254d67f9073e\n responses:\n '200':\n description: Sync status.\n content:\n application/vnd.polaris.integrations.tims.connection-sync-status-1+json;charset=UTF-8:\n schema:\n type: object\n description: Current state and history of the connection synchronization process.\n required:\n - status\n properties:\n status:\n type: string\n description: Current status of the sync process.\n enum:\n - PENDING\n - RUNNING\n - COMPLETE\n - ERROR\n startedAt:\n type: string\n format: date-time\n description: The time that the latest sync started.\n finishedAt:\n type: string\n format: date-time\n description: The time that the latest sync finished.\n message:\n type:\n - string\n - 'null'\n description: Error message if the sync failed.\n lastSuccess:\n type: string\n format: date-time\n description: The time that the sync last succeeded.\n example:\n status: COMPLETE\n startedAt: '2025-01-15T14:30:00Z'\n finishedAt: '2025-01-15T14:35:00Z'\n lastSuccess: '2025-01-15T14:35:00Z'\n example:\n status: COMPLETE\n startedAt: '2024-01-15T14:00:00Z'\n finishedAt: '2024-01-15T14:45:00Z'\n lastSuccess: '2024-01-15T14:45:00Z'\n '401':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/401'\n '403':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/403'\n '404':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D/get/responses/404'\n /api/integrations/tool-connectors/connections/{connectionId}/mappings:\n post:\n operationId: createMapping\n summary: Create mapping\n description: |\n Create a new mapping between a Polaris project/branch and an external tool project/version.\n tags:\n - Connection Mappings\n parameters:\n - $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D/get/parameters/0'\n requestBody:\n required: true\n content:\n application/vnd.polaris.integrations.tims.connection-branch-mapping-1+json;charset=UTF-8:\n schema:\n type: object\n required:\n - applicationId\n - projectId\n - branchId\n - externalProjectName\n - externalVersionName\n - properties\n properties:\n applicationId:\n type: string\n format: uuid\n description: The ID of the Polaris application.\n example: a1b2c3d4-e5f6-7890-abcd-ef1234567890\n projectId:\n type: string\n format: uuid\n description: The ID of the Polaris project.\n example: b2c3d4e5-f6a7-8901-bcde-f12345678901\n branchId:\n type: string\n format: uuid\n description: The ID of the Polaris branch.\n example: c3d4e5f6-a7b8-9012-cdef-123456789012\n externalProjectName:\n type: string\n description: The name of the project in the external system.\n example: example-project\n externalVersionName:\n type: string\n description: The name of the version in the external system.\n example: 1.0.0\n properties:\n type: object\n description: Properties containing values for the projectForm and versionForm from the ToolConnector. For Black Duck, this would typically include project and version UUIDs.\n example:\n applicationId: 0197c6b5-571a-79e0-9412-8d7b09b91b51\n projectId: 550e8400-e29b-41d4-a716-446655440000\n branchId: 38a28c8c-6e32-4a71-9a8d-254d67f9073e\n externalProjectName: My Black Duck Project\n externalVersionName: v1.0.0\n properties:\n project: 550e8400-e29b-41d4-a716-446655440000\n version: 38a28c8c-6e32-4a71-9a8d-254d67f9073e\n responses:\n '201':\n description: Mapping created successfully.\n content:\n application/vnd.polaris.integrations.tims.connection-branch-mapping-1+json;charset=UTF-8:\n schema:\n type: object\n description: Represents a mapping between a Polaris project/branch and an external tool project/version.\n required:\n - id\n - connectionId\n - applicationId\n - projectId\n - branchId\n - createdAt\n - updatedAt\n - integration\n - externalProjectName\n - externalVersionName\n - properties\n - syncState\n properties:\n id:\n type: string\n format: uuid\n description: The ID of the mapping.\n connectionId:\n type: string\n format: uuid\n description: The ID of the connection.\n applicationId:\n type: string\n format: uuid\n description: The ID of the Polaris application.\n projectId:\n type: string\n format: uuid\n description: The ID of the Polaris project.\n branchId:\n type: string\n format: uuid\n description: The ID of the Polaris branch.\n createdAt:\n type: string\n format: date-time\n description: The time that the mapping was created.\n updatedAt:\n type: string\n format: date-time\n description: The time that the mapping was last updated.\n integration:\n $ref: >-\n #/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D~1project-mappings/get/responses/200/content/application~1vnd.polaris.integrations.tims.connection-project-mapping-1%2Bjson%3Bcharset%3DUTF-8/schema/properties/_items/items/properties/integration\n externalProjectName:\n type: string\n description: The name of the project in the external system.\n externalVersionName:\n type: string\n description: The name of the version in the external system.\n properties:\n type: object\n description: Properties containing values for the projectForm and versionForm from the ToolConnector. For Black Duck, this would typically include project and version UUIDs.\n syncState:\n $ref: >-\n #/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D~1sync-data~1status/get/responses/200/content/application~1vnd.polaris.integrations.tims.connection-sync-status-1%2Bjson%3Bcharset%3DUTF-8/schema\n example:\n id: 5c92259d-528f-4ed6-8fd4-c3c787c42508\n connectionId: 0197c6b5-571a-79e0-9412-8d7b09b91b51\n applicationId: a1b2c3d4-e5f6-7890-abcd-ef1234567890\n projectId: b2c3d4e5-f6a7-8901-bcde-f12345678901\n branchId: c3d4e5f6-a7b8-9012-cdef-123456789012\n createdAt: '2025-01-15T14:30:00Z'\n updatedAt: '2025-01-15T14:30:00Z'\n integration:\n id: 8481683c-cdbe-4e6b-88ad-a1d2fe4abe5d\n name: Black Duck SCA\n externalProjectName: example-project\n externalVersionName: 1.0.0\n properties:\n project: d4e5f6a7-b8c9-0123-defg-456789012345\n version: e5f6a7b8-c9d0-1234-efgh-5678901234567\n syncState:\n status: COMPLETE\n startedAt: '2025-01-15T14:30:00Z'\n finishedAt: '2025-01-15T14:35:00Z'\n lastSuccess: '2025-01-15T14:35:00Z'\n example:\n id: 5c92259d-528f-4ed6-8fd4-c3c787c42508\n connectionId: 0197c6b5-571a-79e0-9412-8d7b09b91b51\n applicationId: 0197c6b5-571a-79e0-9412-8d7b09b91b51\n projectId: 550e8400-e29b-41d4-a716-446655440000\n branchId: 38a28c8c-6e32-4a71-9a8d-254d67f9073e\n createdAt: '2024-01-15T10:30:00Z'\n updatedAt: '2024-01-15T10:30:00Z'\n integration:\n id: 8481683c-cdbe-4e6b-88ad-a1d2fe4abe5d\n name: Black Duck SCA\n externalProjectName: My Black Duck Project\n externalVersionName: v1.0.0\n properties:\n project: 550e8400-e29b-41d4-a716-446655440000\n version: 38a28c8c-6e32-4a71-9a8d-254d67f9073e\n syncState:\n status: PENDING\n '400':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/post/responses/400'\n '401':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/401'\n '403':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/403'\n '404':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D/get/responses/404'\n /api/integrations/tool-connectors/connections/{connectionId}/mappings/search:\n post:\n operationId: searchMappings\n summary: Search mappings\n description: |\n Search for mappings between Polaris projects/branches and external tool projects/versions.\n tags:\n - Connection Mappings\n parameters:\n - $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D~1project-mappings/get/parameters/0'\n - name: _offset\n in: query\n required: false\n description: Index offset for page.\n schema:\n type: integer\n default: 0\n example: 0\n - name: _limit\n in: query\n required: false\n description: Items per page.\n schema:\n type: integer\n default: 20\n maximum: 100\n example: 50\n - name: includeDeleted\n in: query\n required: false\n description: Whether to include deleted mappings.\n schema:\n type: boolean\n default: false\n example: false\n - name: id\n in: query\n required: false\n description: Filter by mapping ID.\n schema:\n type: string\n example: 5c92259d-528f-4ed6-8fd4-c3c787c42508\n - name: projectId\n in: query\n required: false\n description: Filter by Polaris project ID.\n schema:\n type: string\n example: b2c3d4e5-f6a7-8901-bcde-f12345678901\n - name: applicationId\n in: query\n required: false\n description: Filter by Polaris application ID.\n schema:\n type: string\n example: a1b2c3d4-e5f6-7890-abcd-ef1234567890\n - name: branchId\n in: query\n required: false\n description: Filter by Polaris branch ID.\n schema:\n type: string\n example: c3d4e5f6-a7b8-9012-cdef-123456789012\n requestBody:\n required: false\n content:\n application/vnd.polaris.integrations.tims.connection-mapping-search-1+json;charset=UTF-8:\n schema:\n type: object\n properties:\n properties:\n type: object\n description: Optional filter properties for matching mappings.\n additionalProperties: true\n example:\n properties:\n project: 550e8400-e29b-41d4-a716-446655440000\n version: 38a28c8c-6e32-4a71-9a8d-254d67f9073e\n responses:\n '200':\n description: Mapping search results.\n content:\n application/vnd.polaris.integrations.tims.connection-branch-mapping-1+json;charset=UTF-8:\n schema:\n type: object\n required:\n - _items\n - _collection\n - _links\n properties:\n _items:\n type: array\n description: List of connection mappings.\n items:\n $ref: >-\n #/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D~1mappings/post/responses/201/content/application~1vnd.polaris.integrations.tims.connection-branch-mapping-1%2Bjson%3Bcharset%3DUTF-8/schema\n _collection:\n type: object\n description: Collection metadata.\n properties:\n itemCount:\n type: integer\n description: Total number of items in the collection.\n example: 10\n currentPage:\n type: integer\n description: The current page number of the results (one-based).\n example: 1\n pageCount:\n type: integer\n description: Total number of pages.\n example: 1\n _type:\n type: string\n description: The type of collection being returned.\n example: connection-mappings\n _links:\n type: array\n description: Links related to the collection.\n items:\n type: object\n description: Represents a hypermedia link for navigation.\n required:\n - href\n - rel\n - method\n properties:\n href:\n type: string\n description: URL of the link.\n rel:\n type: string\n description: Relation type of the link.\n method:\n type: string\n description: HTTP method to use for the link.\n example:\n href: /api/integrations/tool-connectors/connections/0197c6b5-571a-79e0-9412-8d7b09b91b51\n rel: self\n method: GET\n example:\n _items:\n - id: 5c92259d-528f-4ed6-8fd4-c3c787c42508\n connectionId: 0197c6b5-571a-79e0-9412-8d7b09b91b51\n applicationId: 0197c6b5-571a-79e0-9412-8d7b09b91b51\n projectId: 550e8400-e29b-41d4-a716-446655440000\n branchId: 38a28c8c-6e32-4a71-9a8d-254d67f9073e\n createdAt: '2024-01-15T10:30:00Z'\n updatedAt: '2024-01-15T10:30:00Z'\n integration:\n id: 8481683c-cdbe-4e6b-88ad-a1d2fe4abe5d\n name: Black Duck SCA\n externalProjectName: My Black Duck Project\n externalVersionName: v1.0.0\n properties:\n project: 550e8400-e29b-41d4-a716-446655440000\n version: 38a28c8c-6e32-4a71-9a8d-254d67f9073e\n syncState:\n status: COMPLETE\n lastSuccess: '2024-01-15T14:45:00Z'\n _collection:\n itemCount: 1\n currentPage: 1\n pageCount: 1\n _type: connection-branch-mappings\n _links:\n - href: https://polaris.blackduck.com/api/integrations/tool-connectors/connections/0197c6b5-571a-79e0-9412-8d7b09b91b51/mappings/search?_offset=0&_limit=20\n rel: self\n method: POST\n - href: https://polaris.blackduck.com/api/integrations/tool-connectors/connections/0197c6b5-571a-79e0-9412-8d7b09b91b51/mappings/search?_offset=0&_limit=20\n rel: first\n method: POST\n '400':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/post/responses/400'\n '401':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/401'\n '403':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/403'\n '404':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D/get/responses/404'\n /api/integrations/tool-connectors/connections/{connectionId}/project-mappings:\n get:\n operationId: getProjectMappings\n summary: Get project mappings\n description: |\n Search for mappings between Polaris projects/branches and external tool projects/versions, grouped by project.\n tags:\n - Connection Mappings\n parameters:\n - name: connectionId\n in: path\n required: true\n description: The unique identifier of the connection. Use 'any' to get results from all connections, or a specific connectionId to filter to that connection only.\n schema:\n type: string\n example: 0197c6b5-571a-79e0-9412-8d7b09b91b51\n - name: id\n in: query\n required: false\n description: Filter by project mapping ID.\n schema:\n type: string\n example: 5c92259d-528f-4ed6-8fd4-c3c787c42508\n - name: applicationId\n in: query\n required: false\n description: Filter by Polaris application ID.\n schema:\n type: string\n format: uuid\n example: 38a28c8c-6e32-4a71-9a8d-254d67f9073e\n - name: projectId\n in: query\n required: false\n description: Filter by Polaris project ID.\n schema:\n type: string\n format: uuid\n example: 550e8400-e29b-41d4-a716-446655440000\n - name: branchId\n in: query\n required: false\n description: Filter by Polaris branch ID.\n schema:\n type: string\n format: uuid\n example: 660e8400-e29b-41d4-a716-446655440000\n - name: includeDeleted\n in: query\n required: false\n description: Whether to include deleted mappings.\n schema:\n type: boolean\n default: false\n example: true\n - name: _offset\n in: query\n required: false\n description: Index offset for page.\n schema:\n type: integer\n default: 0\n example: 20\n - name: _limit\n in: query\n required: false\n description: Items per page.\n schema:\n type: integer\n default: 20\n maximum: 100\n example: 50\n responses:\n '200':\n description: Project mappings.\n content:\n application/vnd.polaris.integrations.tims.connection-project-mapping-1+json;charset=UTF-8:\n schema:\n type: object\n required:\n - _items\n - _collection\n - _links\n properties:\n _items:\n type: array\n description: List of project mappings.\n items:\n type: object\n required:\n - connectionId\n - applicationId\n - projectId\n - integration\n - externalProjectName\n - syncState\n properties:\n connectionId:\n type: string\n format: uuid\n description: The ID of the connection.\n example: 0197c6b5-571a-79e0-9412-8d7b09b91b51\n applicationId:\n type: string\n format: uuid\n description: The ID of the Polaris application.\n example: a1b2c3d4-e5f6-7890-abcd-ef1234567890\n projectId:\n type: string\n format: uuid\n description: The ID of the Polaris project.\n example: b2c3d4e5-f6a7-8901-bcde-f12345678901\n integration:\n type: object\n description: Represents an integration type that can be connected to.\n required:\n - id\n - name\n properties:\n id:\n type: string\n format: uuid\n description: UUID of the integration type.\n name:\n type: string\n description: Name of the integration type.\n example: Black Duck SCA\n example:\n id: 8481683c-cdbe-4e6b-88ad-a1d2fe4abe5d\n name: Black Duck SCA\n externalProjectName:\n type: string\n description: The name of the project in the external system.\n example: example-project\n syncState:\n $ref: >-\n #/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D~1sync-data~1status/get/responses/200/content/application~1vnd.polaris.integrations.tims.connection-sync-status-1%2Bjson%3Bcharset%3DUTF-8/schema\n _collection:\n type: object\n description: Collection metadata.\n properties:\n itemCount:\n type: integer\n description: Total number of items in the collection.\n example: 10\n currentPage:\n type: integer\n description: The current page number of the results (one-based).\n example: 1\n pageCount:\n type: integer\n description: Total number of pages.\n example: 1\n _type:\n type: string\n description: The type of collection being returned.\n example: connection-mappings\n _links:\n type: array\n description: Links related to the collection.\n items:\n $ref: >-\n #/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D~1mappings~1search/post/responses/200/content/application~1vnd.polaris.integrations.tims.connection-branch-mapping-1%2Bjson%3Bcharset%3DUTF-8/schema/properties/_links/items\n example:\n _items:\n - connectionId: 0197c6b5-571a-79e0-9412-8d7b09b91b51\n applicationId: 0197c6b5-571a-79e0-9412-8d7b09b91b51\n projectId: 550e8400-e29b-41d4-a716-446655440000\n integration:\n id: 8481683c-cdbe-4e6b-88ad-a1d2fe4abe5d\n name: Black Duck SCA\n externalProjectName: My Black Duck Project\n syncState:\n status: COMPLETE\n lastSuccess: '2024-01-15T14:45:00Z'\n _collection:\n itemCount: 1\n currentPage: 1\n pageCount: 1\n _type: connection-mappings\n _links:\n - href: https://polaris.blackduck.com/api/integrations/tool-connectors/connections/any/project-mappings?_offset=0&_limit=20\n rel: self\n method: GET\n - href: https://polaris.blackduck.com/api/integrations/tool-connectors/connections/any/project-mappings?_offset=0&_limit=20\n rel: first\n method: GET\n '400':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/post/responses/400'\n '401':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/401'\n '403':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/403'\n /api/integrations/tool-connectors/connections/{connectionId}/mappings/{mappingId}:\n delete:\n operationId: deleteMapping\n summary: Delete mapping\n description: |\n Delete a mapping between a Polaris project/branch and an external tool project/version.\n tags:\n - Connection Mappings\n parameters:\n - $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D/get/parameters/0'\n - name: mappingId\n in: path\n required: true\n description: The unique identifier of the connection mapping.\n schema:\n type: string\n format: uuid\n example: 5c92259d-528f-4ed6-8fd4-c3c787c42508\n responses:\n '204':\n description: Mapping deleted successfully.\n '401':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/401'\n '403':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections/get/responses/403'\n '404':\n $ref: '#/paths/~1api~1integrations~1tool-connectors~1connections~1%7BconnectionId%7D/get/responses/404'\ncomponents:\n securitySchemes:\n ApiKeyAuth:\n type: apiKey\n in: header\n name: Api-Token\n description: API key authentication using the Authorization header\n"

{}