Xcode Server API Reference: Integrations

An integration is a single execution of your bot.

Creating a New Integration

POST

API

Begins an integration for the specified bot.

Optionally, you can specify shouldClean in the request body to indicate whether the integration should be performed using the latest sources.

Example

https://server.mycompany.com:20343/api/bots/6f0faeb1cc4c55e174cac5ff8100f13b/integrations

Parameters

id (required)

The bot ID.
Type: string
Example: 6f0faeb1cc4c55e174cac5ff8100f13b

Request

Body

        {
    shouldClean: false
}

      

Response: 201

Headers

        Content-Type: application/json
Location: https://server.mycompany.com:20343/integration/b31ad8317300e89b2db73aad3d0194ad
X-XCSAPIVersion: 4

      

Body

        {
        "_id": "b31ad8317300e89b2db73aad3d0194ad",
        "_rev": "3-51e9bed938b457df5bce57bca7625af2",
        "bot": {
          ...
        },
        "shouldClean": false,
        "currentStep": "pending",
        "number": 1,
        "queuedDate": "2015-07-20T20:27:22.516Z",
        "success_streak": 0,
        "doc_type": "integration"
}

      

Response: 404

Body

        {
  "status": 404,
  "message": "Integration not found"
}

      

Retrieving an Integration

GET

/integrations/{id}

Retrieves a single integration.

Example

https://server.mycompany.com:20343/api/integrations/b31ad8317300e89b2db73aad3d0194ad

Parameters

id (required)

The integration ID.
Type: string
Example: b31ad8317300e89b2db73aad3d0194ad

Response: 200

Body

        {
  "_id": "b31ad8317300e89b2db73aad3d0194ad",
  "_rev": "17-869fccee9b37638a719c20b1dcfa6869",
  "number": 1,
  "result": "succeeded",
  "success_streak": 1,
  "bot": {
    ...
  },
  "shouldClean": false,
  "doc_type": "integration",
  "currentStep": "completed",
  "queuedDate": "2015-07-20T21:30:58.971Z",
  "buildServiceFingerprint": "9C:67:D4:4A:00:97:0F:22:7B:B1:68:7E:28:1D:E0:5E:F2:E4:45:7C",
  "startedTime": "2015-07-20T21:30:59.669Z",
  "revisionBlueprint": {
    ...
  },
  "buildResultSummary": {
    "analyzerWarningCount": 0,
    "testFailureCount": 0,
    "testsChange": 220,
    "errorCount": 0,
    "testsCount": 220,
    "testFailureChange": 0,
    "warningChange": 0,
    "regressedPerfTestCount": 0,
    "warningCount": 0,
    "errorChange": 0,
    "improvedPerfTestCount": 0,
    "analyzerWarningChange": 0,
    "codeCoveragePercentage": 0,
    "codeCoveragePercentageDelta": 0
  },
  "endedTime": "2015-07-20T21:31:23.906Z",
  "endedTimeDate": [
    2015,
    7,
    20,
    21,
    31,
    23,
    906
  ],
  "duration": 24.237,
  "ccPercentage": 0,
  "ccPercentageDelta": 0,
  "testedDevices": [
    {
      "osVersion": "10.11",
      "connected": true,
      "simulator": false,
      "modelCode": "MacBookPro11,3",
      "deviceType": "com.apple.mac",
      "modelName": "MacBook Pro",
      "revision": "3-824d6d3e1adedab99b103ab21f6b330d",
      "modelUTI": "com.apple.macbookpro-15-retina-display",
      "name": "server.mycompany.com",
      "trusted": true,
      "doc_type": "device",
      "supported": true,
      "processor": "2.5 GHz Intel Core i7",
      "identifier": "686EE427-E12F-50DF-9D20-455B7E3F15CE-x86_64",
      "enabledForDevelopment": true,
      "serialNumber": "XYZ",
      "platformIdentifier": "com.apple.platform.macosx",
      "ID": "b31ad8317300e89b2db73aad3d005719",
      "architecture": "x86_64",
      "retina": false,
      "isServer": true
    }
  ],
  "testHierarchy": {
    "Sketch": {
      "SketchTests": {
        "testFileWithPath": {
          "676EE417-E15F-50DF-9D20-525B7E3F13CE-x86_64": 1
        },
        "testInitiWithPath": {
          "676EE417-E15F-50DF-9D20-525B7E3F13CE-x86_64": 1
        }
      }
    }
  },
  "perfMetricNames": [
    "Time"
  ],
  "perfMetricKeyPaths": [
    "Sketch.SketchTests.testPerfOpenFile"
  ]
}

      

Response: 404

Body

        {
  "status": 404,
  "message": "Integration not found"
}

      

Deleting an Integration

DELETE

/integrations/{id}

Deletes an integration.

Example

https://server.mycompany.com:20343/api/integrations/b31ad8317300e89b2db73aad3d0194ad

Parameters

id (required)

The integration ID.
Type: string
Example: b31ad8317300e89b2db73aad3d0194ad

Response: 204

Response: 404

Body

        {
  "status": 404,
  "message": "Integration not found"
}

      

Canceling an Integration

POST

API

Cancels a integration currently being executed.

Example

/integrations/{id}/cancel

Parameters

id (required)

The integration ID.
Type: string
Example: b31ad8317300e89b2db73aad3d0194ad

Response: 204

Response: 400

Body

        {
  "status": 400,
  "message": "The integration cannot be canceled because it has been completed already"
}

      

Response: 404

Body

        {
  "status": 404,
  "message": "Integration not found"
}

      

Filtering Integrations for a Bot

GET

/bots/{id}/integrations{?filter,last,number,from,next,prev,count,summary_only}

Retrieve options to perform filters, selections and calculations on all integrations for the specified bot. There are two filter options: non_fatal and with_build_results.

non_fatal: Integrations with a result of type succeeded, test-failures, build-errors, warnings, analyzer-warnings or build-failed.
with_build_results: Integrations containing build summary information.

Examples

https://server.mycompany.com:20343/api/bots/68a5sdf67/integrations?filter=non_fatal

https://server.mycompany.com:20343/api/bots/68a5sdf67/integrations?filter=non_fatal&last=50

https://server.mycompany.com:20343/api/bots/68a5sdf67/integrations?filter=with_build_results

https://server.mycompany.com:20343/api/bots/68a5sdf67/integrations?filter=with_build_results&last=15

https://server.mycompany.com:20343/api/bots/68a5sdf67/integrations?last=1

https://server.mycompany.com:20343/api/bots/68a5sdf67/integrations?number=1

https://server.mycompany.com:20343/api/bots/68a5sdf67/integrations?from=3&next=2

https://server.mycompany.com:20343/api/bots/68a5sdf67/integrations?last=1&summary_only=true

https://server.mycompany.com:20343/api/bots/68a5sdf67/integrations?count=true

Parameters

id (required)

The bot ID.
Type: string
Example: 6f0faeb1cc4c55e174cac5ff8100f13b

filter (optional)

Choices: non_fatal, with_build_results
Type: string

last (optional)

On output, the last specified number of integrations for the specified bot.
Type: number

number (optional)

On output, the integration with the given number for the specified bot.
Type: number

from (optional)

The integration number from which to start filtering. This option requires next or prev to be specified as well.
Type: number

next (optional)

It indicates the number of integrations you want filtered beyond the starting point. This option requires from to be specified as well.
Type: number

prev (optional)

It indicates the number of integrations you want filtered beyond the starting point. This option requires from to be specified as well.
Type: number

count (optional)

On output, the number of integrations for the specified bot.
Type: number

summary_only (optional)

A Boolean value that indicates whether to return a brief summary instead of the regular payload.
Type: boolean

Response: 200

Body

        {
  "count": 1,
  "results": [
    {
      "_id": "b31ad8317300e89b2db73aad3d0194ad",
      "_rev": "17-869fccee9b37638a719c20b1dcfa6869",
      "number": 1,
      "result": "succeeded",
      "success_streak": 1,
      "bot": {
        ...
      },
      "shouldClean": false,
      "doc_type": "integration",
      "currentStep": "completed",
      "queuedDate": "2015-07-20T21:30:58.971Z",
      "buildServiceFingerprint": "9C:67:D4:4A:00:97:0F:22:7B:B1:68:7E:28:1D:E0:5E:F2:E4:45:7C",
      "startedTime": "2015-07-20T21:30:59.669Z",
      "revisionBlueprint": {
        ...
      },
      "buildResultSummary": {
        "analyzerWarningCount": 0,
        "testFailureCount": 0,
        "testsChange": 220,
        "errorCount": 0,
        "testsCount": 220,
        "testFailureChange": 0,
        "warningChange": 0,
        "regressedPerfTestCount": 0,
        "warningCount": 0,
        "errorChange": 0,
        "improvedPerfTestCount": 0,
        "analyzerWarningChange": 0,
        "codeCoveragePercentage": 0,
        "codeCoveragePercentageDelta": 0
      },
      "endedTime": "2015-07-20T21:31:23.906Z",
      "endedTimeDate": [
        2015,
        7,
        20,
        21,
        31,
        23,
        906
      ],
      "duration": 24.237,
      "ccPercentage": 0,
      "ccPercentageDelta": 0
    }
  ]
}

      

Response: 400

Body

        {
  "status": 400,
  "message": "Bad request: filter 'foobar' is not supported"
}

      

Response: 404

Body

        {
  "status": 404,
  "message": "Integration not found"
}

      

Filtering Integrations for All Bots

GET

/integrations{?filter,last,count,summary_only}

Retrieve options to perform filters, selections and calculations on all integrations. There are two filter options: non_fatal and with_build_results.

non_fatal: Integrations with a result of type succeeded, test-failures, build-errors, warnings, analyzer-warnings or build-failed.
with_build_results: Integrations containing build summary information.

Example

https://server.mycompany.com:20343/api/integrations?filter=non_fatal

https://server.mycompany.com:20343/api/integrations?filter=non_fatal&last=50

https://server.mycompany.com:20343/api/integrations?filter=with_build_results

https://server.mycompany.com:20343/api/integrations?filter=with_build_results&last=15

https://server.mycompany.com:20343/api/integrations?last=1

https://server.mycompany.com:20343/api/integrations?last=1&summary_only=true

https://server.mycompany.com:20343/api/integrations?count=true

Parameters

filter (optional)

Choices: non_fatal, with_build_results
Type: string

last (optional)

The last specified number of integrations.
Type: number

count (optional)

The total number of integrations.
Type: number

summary_only (optional)

A Boolean value that indicates whether to return a brief summary instead of the regular payload.
Type: boolean

Response: 200

Body

        {
  "count": 1,
  "results": [
    {
      "_id": "b31ad8317300e89b2db73aad3d0194ad",
      "_rev": "17-869fccee9b37638a719c20b1dcfa6869",
      "number": 1,
      "result": "succeeded",
      "success_streak": 1,
      "bot": {
        ...
      },
      "shouldClean": false,
      "doc_type": "integration",
      "currentStep": "completed",
      "queuedDate": "2015-07-20T21:30:58.971Z",
      "buildServiceFingerprint": "9C:67:D4:4A:00:97:0F:22:7B:B1:68:7E:28:1D:E0:5E:F2:E4:45:7C",
      "startedTime": "2015-07-20T21:30:59.669Z",
      "revisionBlueprint": {
        ...
      },
      "buildResultSummary": {
        "analyzerWarningCount": 0,
        "testFailureCount": 0,
        "testsChange": 220,
        "errorCount": 0,
        "testsCount": 220,
        "testFailureChange": 0,
        "warningChange": 0,
        "regressedPerfTestCount": 0,
        "warningCount": 0,
        "errorChange": 0,
        "improvedPerfTestCount": 0,
        "analyzerWarningChange": 0,
        "codeCoveragePercentage": 0,
        "codeCoveragePercentageDelta": 0
      },
      "endedTime": "2015-07-20T21:31:23.906Z",
      "endedTimeDate": [
        2015,
        7,
        20,
        21,
        31,
        23,
        906
      ],
      "duration": 24.237,
      "ccPercentage": 0,
      "ccPercentageDelta": 0
    }
  ]
}

      

Response: 400

Body

        {
  "status": 400,
  "message": "Filter 'foobar' is not supported"
}

      

Retrieving Tests for an Integration

POST

/integrations/{id}/test/batch{?deviceIdentifier}

Retrieves the tests for an integration. Optionally, you can specify the deviceIdentifier to filter the tests for the given device.

Examples

https://server.mycompany.com:20343/api/integrations/b31ad8317300e89b2db73aad3d0194ad/test/batch

https://server.mycompany.com:20343/api/integrations/b31ad8317300e89b2db73aad3d0194ad/test/batch?676EE417-E15F-50DF-9D20-525B7E3F13CE-x86_64

Parameters

id (required)

The integration ID.
Type: string
Example: b31ad8317300e89b2db73aad3d0194ad

deviceIdentifier (optional)

The device ID.
Type: string
Example: 676EE417-E15F-50DF-9D20-525B7E3F13CE-x86_64

Response: 200

Body

        {
  "count": 2,
  "results": [
    {
      "_id": "b31ad8317300e89b2db73aad3d049f7f",
      "_rev": "1-37569504c8dee4e1de5e1ed5341833f6",
      "perfMetrics": {},
      "testableBlueprintName": "Sketch",
      "passed": 1,
      "path": [
        "Sketch",
        "SketchFileTests",
        "testOpenFile"
      ],
      "title": "testOpenFile",
      "testedDevice": {
        "osVersion": "10.11",
        "connected": true,
        "simulator": false,
        "modelCode": "MacBookPro11,3",
        "deviceType": "com.apple.mac",
        "modelName": "MacBook Pro",
        "revision": "3-824d6d3e1adedab99b103ab21f6b330d",
        "modelUTI": "com.apple.macbookpro-15-retina-display",
        "name": "server.mycompany.com",
        "trusted": true,
        "doc_type": "device",
        "supported": true,
        "processor": "2.5 GHz Intel Core i7",
        "identifier": "676EE417-E15F-50DF-9D20-525B7E3F13CE-x86_64",
        "enabledForDevelopment": true,
        "serialNumber": "XYZ",
        "platformIdentifier": "com.apple.platform.macosx",
        "ID": "b31ad8317300e89b2db73aad3d005719",
        "architecture": "x86_64",
        "retina": false,
        "isServer": true
      },
      "date": [
        2015,
        7,
        20
      ],
      "deviceIdentifier": "676EE417-E15F-50DF-9D20-525B7E3F13CE-x86_64",
      "endTime": 2,
      "keyPath": "Sketch.SketchFileTests.testOpenFile",
      "doc_type": "test",
      "failureSummaries": [],
      "integration": "b31ad8317300e89b2db73aad3d049327",
      "startTime": 1,
      "dateISO8601": "2015-07-20T21:31:22.590Z",
      "testableBlueprintPath": "Sketch.xcodeproj"
    },
    {
      "_id": "b31ad8317300e89b2db73aad3d04a31c",
      "_rev": "1-64fe6ec373b4e3075cc299cf411fe425",
      "perfMetrics": {},
      "testableBlueprintName": "Sketch",
      "passed": 1,
      "path": [
        "Sketch",
        "SketchFileTests",
        "testOpenFile"
      ],
      "title": "testOpenFile",
      "testedDevice": {
        "osVersion": "10.11",
        "connected": true,
        "simulator": false,
        "modelCode": "MacBookPro11,3",
        "deviceType": "com.apple.mac",
        "modelName": "MacBook Pro",
        "revision": "3-824d6d3e1adedab99b103ab21f6b330d",
        "modelUTI": "com.apple.macbookpro-15-retina-display",
        "name": "server.mycompany.com",
        "trusted": true,
        "doc_type": "device",
        "supported": true,
        "processor": "2.5 GHz Intel Core i7",
        "identifier": "676EE417-E15F-50DF-9D20-525B7E3F13CE-x86_64",
        "enabledForDevelopment": true,
        "serialNumber": "XYZ",
        "platformIdentifier": "com.apple.platform.macosx",
        "ID": "b31ad8317300e89b2db73aad3d005719",
        "architecture": "x86_64",
        "retina": false,
        "isServer": true,
        "tinyID": "6C69E42"
      },
      "date": [
        2015,
        7,
        20
      ],
      "deviceIdentifier": "676EE417-E15F-50DF-9D20-525B7E3F13CE-x86_64",
      "endTime": 2,
      "keyPath": "Sketch.SketchFileTests.testOpenFile",
      "doc_type": "test",
      "failureSummaries": [],
      "integration": "b31ad8317300e89b2db73aad3d049327",
      "startTime": 1,
      "dateISO8601": "2015-07-20T21:31:22.591Z",
      "testableBlueprintPath": "Sketch.xcodeproj"
    }
  ]
}

      

Response: 404

Body

        {
  "status": 404,
  "message": "Integration not found"
}

      

Retrieving Commits for an Integration

GET

/integrations/{id}/commits

Retrieves the test information list for a given integration and device identifier.

Example

https://server.mycompany.com:20343/api/integrations/b31ad8317300e89b2db73aad3d0194ad/commits

Parameters

id (required)

The integration ID.
Type: string
Example: b31ad8317300e89b2db73aad3d0194ad

Response: 200

Body

        {
  "_id": "b31ad8317300e89b2db73aad3d0194ad",
  "_rev": "3-7fda81759371fb8644058c0cfc83737e",
  "commits": {
    "6446FCB001D8C2E70EC59D119F3E3318109CE1A9": [
      {
        "XCSCommitCommitChangeFilePaths": [
          {
            "status": 4,
            "filePath": "Sketch.xcodeproj/project.pbxproj"
          },
          {
            "status": 1,
            "filePath": "Sketch.xcodeproj/project.xcworkspace/xcshareddata/Sketch.xcscmblueprint"
          },
          {
            "status": 1,
            "filePath": "Sketch.xcodeproj/project.xcworkspace/xcshareddata/Sketch.xccheckout"
          }
        ],
        "XCSCommitMessage": "Remove run scripts (is obsolete and was causing a warning)",
        "XCSBlueprintRepositoryID": "6446FCB001D8C2E70EC59D119F3E3318109CE1A9",
        "XCSCommitContributor": {
          "XCSContributorEmails": [
            "appleseed@mycompany.com"
          ],
          "XCSContributorName": "John Appleseed",
          "XCSContributorDisplayName": "John Appleseed"
        },
        "XCSCommitHash": "3982fd5a6dd349c3673c9f91a96baf69eedc44a1",
        "XCSCommitTimestamp": "2015-06-19T18:37:31.000Z",
        "XCSCommitTimestampDate": [
          2015,
          6,
          19,
          18,
          37,
          31,
          0
        ]
      }
    ]
  },
  "integration": "b31ad8317300e89b2db73aad3d049327",
  "botID": "b31ad8317300e89b2db73aad3d048d19",
  "endedTimeDate": [
    2015,
    7,
    20,
    21,
    31,
    1,
    830
  ],
  "doc_type": "commit"
}

      

Response: 404

Body

        {
  "status": 404,
  "message": "Integration not found"
}

      

Retrieving Issues for an Integration

GET

/integrations/{id}/issues

Retrieves the test information list of issues for a given integration and device identifier.

Example

https://server.mycompany.com:20343/api/integrations/b31ad8317300e89b2db73aad3d0194ad/issues

Parameters

id (required)

The integration ID.
Type: string
Example: b31ad8317300e89b2db73aad3d0194ad

Response: 200

Body

        {
  "buildServiceErrors": [],
  "buildServiceWarnings": [],
  "triggerErrors": [],
  "errors": {
    "unresolvedIssues": [],
    "freshIssues": [
      {
        "_id": "37f997baa062fc9576f80f117b0244db",
        "_rev": "3-e22d523aaaefcba794ee958184008f65",
        "message": "Cannot assign a value of type 'String' to a value of type 'Int'",
        "type": "error",
        "issueType": "Swift Compiler Error",
        "commits": [
          {
            "XCSCommitCommitChangeFilePaths": [
              {
                "status": 4,
                "filePath": "testing-app/XMCStock.swift"
              }
            ],
            "XCSCommitMessage": "Forcing an error on purpose to test issues",
            "XCSBlueprintRepositoryID": "090F3C64B0F773799E72487C8CB2AA2DCE01DCAA",
            "XCSCommitContributor": {
              "XCSContributorEmails": [
                "jappleseed@mycompany.com"
              ],
              "XCSContributorName": "John Appleseed",
              "XCSContributorDisplayName": "John Appleseed"
            },
            "XCSCommitHash": "ea0e20d780a36d49003dcbc5e65592cf24a097db",
            "XCSCommitTimestamp": "2015-07-24T02:06:17.000Z"
          }
        ],
        "target": "testing-app",
        "documentFilePath": "DojoTesting/testing-app/XMCStock.swift",
        "documentLocationData": "...",
        "lineNumber": 19,
        "integrationID": "b31ad8317300e89b2db73aad3d0194ad",
        "age": 0,
        "status": 0
      }
    ],
    "resolvedIssues": [],
    "silencedIssues": []
  },
  "warnings": {
    "unresolvedIssues": [],
    "freshIssues": [],
    "resolvedIssues": [],
    "silencedIssues": []
  },
  "testFailures": {
    "unresolvedIssues": [],
    "freshIssues": [],
    "resolvedIssues": [],
    "silencedIssues": []
  },
  "analyzerWarnings": {
    "unresolvedIssues": [],
    "freshIssues": [],
    "resolvedIssues": [],
    "silencedIssues": []
  }
}

      

Response: 404

Body

        {
  "status": 404,
  "message": "Integration not found"
}

      

Retrieving Files for an Integration

GET

/integrations/{id}/files

Retrieves the list of files for a given integration. The results property contains entries for:

xcodebuild result bundle (zip)
build service log
xcodebuild log
source control log
session log

Example

https://server.mycompany.com:20343/api/integrations/b31ad8317300e89b2db73aad3d0194ad/files

Parameters

id (required)

The integration ID.
Type: string
Example: b31ad8317300e89b2db73aad3d0194ad

Response: 200

Body

        {
    /* The number of files */
 
    "count": 5,
 
    /* The list of files associated with the integration */
    "results": [
        {
            /* Whether the file can be downloaded anonymously */
            "allowAnonymousAccess": false,
 
            /* The size of the file (in bytes) */
            "size": 528254,
 
            /* The name of the file */
            "fileName": "xcodebuild_result.bundle.zip",
 
            /* The associated integration ID */
            "integrationID": "bb5b5dfa1c4abff347d28bed7e00bf87",
 
            /* The relative path */
            "relativePath": "bb5b5dfa1c4abff347d28bed7e00b381-Sketch/1/xcodebuild_result.bundle.zip"
        }
        ...
        ...
    ]
}

      

Response: 404

Body

        {
  "status": 404,
  "message": "Integration not found"
}

      