# Integration Builds

{% hint style="warning" %}
These APIs uses the [Agent token](https://docs.sealights.io/knowledgebase/setup-and-configuration/getting-started/steps-for-successful-onboarding/generating-a-token#agent-tokens).
{% endhint %}

## Generating an Integration Build  <a href="#generating-an-integration-build" id="generating-an-integration-build"></a>

### Create/Update from running components <a href="#create-update-from-running-components" id="create-update-from-running-components"></a>

Generate an integration build with a specific build name based on all the components reporting on a specific `labId`\
All the components must be already deployed and reporting to Sealights at the time the API is called.

{% code overflow="wrap" lineNumbers="true" %}

```
POST /sl-api/v1/agent-apis/lab-ids/{labId}/integration-build
```

{% endcode %}

{% hint style="info" %}
As the components must be already deployed and reporting to Sealights at the time the API is called, you will not be able to use this for components like UI that come up in the browser only at the time the tests are actually run\
To work around this, you can either provide its details in the **additionalComponents** parameter, or open the UI programmatically just before calling the API
{% endhint %}

{% hint style="warning" %}
The integration build name and its components must be different otherwise coverage will not be collected for the component
{% endhint %}

#### Request details <a href="#request-details" id="request-details"></a>

**Request Parameters**

<table><thead><tr><th>Parameter</th><th width="240.0859375">Description</th><th width="143.08203125">Parameter Type</th><th>Data Type</th></tr></thead><tbody><tr><td><strong>labId</strong></td><td>Lab Id</td><td>path</td><td>string</td></tr><tr><td><strong>buildName</strong></td><td>Build name</td><td>body</td><td>string</td></tr><tr><td><strong>additionalComponents</strong></td><td>additional components to be added to the integration build</td><td>body</td><td>array of<br>{<br>"bsid": "string",<br>"appName": "string",<br>"branchName": "string",<br>"buildName": "string"<br>}</td></tr><tr><td><strong>forceFailedComponents</strong></td><td>Force the creation of the integration build even when some of the components failed to be reported to Sealights during their build scan</td><td>body</td><td>boolean</td></tr></tbody></table>

**Request Body**

String containing the name of the build (`build`Name). This build must be a new build name, never reported for this integration build.\
`additionalComponents` Optional information that can be used to provide additional components not alive and reporting to Sealights at the time the API is called.\
`forceFailedComponents` Optional flag that can be used to force the creation of the integration build even when some of the components failed to be reported to Sealights during their build scan. It is important to understand that even though the integration build will be created, it will not be representing the correct deployment and coverage will not be captured for the components that did not report a complete build scan

**Response Status Codes**

<table><thead><tr><th width="100.55078125">Code</th><th width="150.03515625">Status</th><th>Description</th></tr></thead><tbody><tr><td>200</td><td>OK</td><td>Integration build created successfully</td></tr><tr><td>400</td><td>BAD REQUEST</td><td>Integration build name already exists or unresolved components</td></tr><tr><td>409</td><td>CONFLICT</td><td>No running agents were reported from lab</td></tr><tr><td>500</td><td> </td><td>Internal server error</td></tr></tbody></table>

#### Request Samples  <a href="#request-samples" id="request-samples"></a>

{% tabs %}
{% tab title="HTTP" %}
**Sample HTTP Request and Response**

{% code overflow="wrap" lineNumbers="true" %}

```http
POST /sl-api/v1/agent-apis/lab-ids/{labId}/integration-build HTTP/1.1
Authorization: Bearer {sealights-agent-token}
Accept: application/json
Content-Type: application/json

{
  "buildName": "{build-name}"
  "additionalComponents": [
    { "bsid": "123456789" },
    { "appName": "app1", "branchName": "master", "buildName": "1.1.99" }
  ]
}

HTTP/1.1 200 OK
Content-Type: application/json
{
  "buildSessionId": "integration-bsid"
}

HTTP/1.1 400 BAD REQUEST
HTTP/1.1 409 CONFLICT
```

{% endcode %}
{% endtab %}

{% tab title="Shell" %}
**Sample Shell Command and Response**

{% code overflow="wrap" lineNumbers="true" %}

```sh
curl -X POST "https://$DOMAIN/sl-api/v1/agent-apis/lab-ids/{labId}/integration-build" \
  -H "Authorization: Bearer $SEALIGHTS_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "buildName": "build-name", "additionalComponents": [ {"bsid": "123456789" },{"appName": "app1", "branchName": "master", "buildName": "1.1.99" }]}'  
  
200 OK
Content-Type: application/json
{
  "buildSessionId": "integration-bsid"
}

400 BAD REQUEST
409 CONFLICT
```

{% endcode %}
{% endtab %}

{% tab title="Powershell" %}
**Sample Powershell Command and Response**

{% code overflow="wrap" lineNumbers="true" %}

```powershell
$Params = @{
    Method = "Post"
    Uri="https://$DOMAIN/sl-api/v1/agent-apis/lab-ids/{labId}/integration-build"
    Headers=@{
        Authorization="Bearer $Env:SEALIGHTS_AGENT_TOKEN"
        "Content-Type"="application/json"
    }
}
$Body=@{'buildName'="$Env:BUILD_NUMBER"}

Invoke-RestMethod @Params -Body ($Body|ConvertTo-Json)
```

{% endcode %}
{% endtab %}
{% endtabs %}

#### Cockpit events <a href="#cockpit-events" id="cockpit-events"></a>

You can view events received by Sealights in the cockpit under the Lab Monitor.\
The type of events you can see are:

<table><thead><tr><th width="418.10546875">Event type</th><th width="72.83984375">Type</th><th>Description</th></tr></thead><tbody><tr><td>INTEGRATION_BUILD_CREATED</td><td>Info</td><td>Integration build created successfully</td></tr><tr><td>INTEGRATION_BUILD_MISSING_APPS</td><td>Info</td><td>Some apps that are already part of the integration build are not currently reporting</td></tr><tr><td>INTEGRATION_BUILD_ERROR_ALREADY_EXISTS</td><td>Error</td><td>Integration build name already exists. <code>buildName</code> must be unique for every new integration build</td></tr><tr><td>INTEGRATION_BUILD_ERROR_NO_LIVE_AGENTS</td><td>Error</td><td>Cannot create new integration build since no live agents detected for the given lab ID</td></tr><tr><td>INTEGRATION_BUILD_ERROR_FAILED_TO_CREATE</td><td>Error</td><td>Failed to create integration build. See description for more details</td></tr></tbody></table>

#### Spin up the UI programmatically <a href="#spin-up-the-ui-programmatically" id="spin-up-the-ui-programmatically"></a>

As mentioned above in the note, as the components must be already deployed and reporting to Sealights at the time the API is called, you will not be able to use this for components like UI that come up in the browser only at the time the tests are actually runTo work around this, you can either provide its details in the **additionalComponents** parameter, or open the UI programmatically just before calling the API.

Here is sample code to spin up the UI programmatically:

{% code overflow="wrap" lineNumbers="true" %}

```
BUILD_ID=ignore_bk google-chrome --headless http://${ENV_URL}  --disable-gpu > chrome.log &
CHROME_PID=$!
sleep 30 # Gives time for the UI to come up and browser agent start reporting, update according to UI spinup time
curl -X POST "https://$DOMAIN/sl-api/v1/agent-apis/lab-ids/{labId}/integration-build" -H "Authorization: Bearer $SEALIGHTS_AGENT_TOKEN" -H "Content-Type: application/json" -d '{ "buildName": "build-name"}'
sleep 10
kill ${CHROME_PID}
```

{% endcode %}

### Create/Update from an explicit list of components <a href="#create-update-from-an-explicit-list-of-components" id="create-update-from-an-explicit-list-of-components"></a>

Create/update integration build with a specific build session ID (`bsid`). If the requested `bsid` does not exist, create it. Otherwise, add components to it.

{% code overflow="wrap" lineNumbers="true" %}

```
PUT /sl-api/v1/agent-apis/integration-builds/{bsid}/components
```

{% endcode %}

To delete components see [#delete-integration-builds-components](#delete-integration-builds-components "mention") below.

#### Request details <a href="#request-details.1" id="request-details.1"></a>

**Request Parameters**

| bsid | Build Session ID |
| ---- | ---------------- |

**Request Body**

Array of build session IDs **or** component details (app name, branch name, build name).\
If both `bsid` and `app-branch-build` are supplied, `app-branch-build` are prioritized.

**Response Status Codes**

<table data-header-hidden><thead><tr><th width="92.453125">Code</th><th width="137.59765625">Status</th><th>Description</th></tr></thead><tbody><tr><td>200</td><td>OK</td><td>Components successfully updated</td></tr><tr><td>409</td><td>CONFLICT</td><td>Some components are invalid</td></tr></tbody></table>

#### Request Samples  <a href="#request-samples.1" id="request-samples.1"></a>

{% tabs %}
{% tab title="HTTP" %}
**Sample HTTP request and response**

{% code overflow="wrap" lineNumbers="true" %}

```http
DELETE /sl-api/v1/agent-apis/integration-builds/{bsid}/components HTTP/1.1
Authorization: Bearer {sealights-agent-token}
Content-Type: application/json
[
  {
    "bsid": "component-bsid",
    "appName": "app",
    "branchName": "branch",
    "buildName": "build"
  }
]
HTTP/1.1 200 OK
HTTP/1.1 409 CONFLICT
```

{% endcode %}
{% endtab %}

{% tab title="Shell" %}
**Sample Shell command and response**

{% code overflow="wrap" lineNumbers="true" %}

```sh
curl -X DELETE "https://$DOMAIN/sl-api/v1/agent-apis/integration-builds/$BSID/components" \
  -H "Authorization: Bearer $SEALIGHTS_AGENT_TOKEN" \
  -H "Content-Type: application/json"  \
  -d "[{\"bsid\":\"component-bsid\",\"appName\":\"app\",\"branchName\":\"branch\",\"buildName\":\"build\"}]"


200 OK

409 CONFLICT
```

{% endcode %}
{% endtab %}
{% endtabs %}

### Automatic Integration Build Creation <a href="#automatic-integration-build-creation" id="automatic-integration-build-creation"></a>

You may configure an Integration labId to Automatically create Integration Builds. To do this you must:

* Create an integration labId configured with AutomaticBuild = true. Currently, you must [contact Sealights support](https://docs.sealights.io/knowledgebase/contact-support) to do this.
* Understand the scenarios where an Integration Build will be created automatically:[#sealightscdagent-cdagentintegrationbuildtriggers](https://docs.sealights.io/knowledgebase/setup-and-configuration/sealights-agents-and-plugins/cd-agent#sealightscdagent-cdagentintegrationbuildtriggers "mention").

## Delete Integration Build's Components <a href="#delete-integration-builds-components" id="delete-integration-builds-components"></a>

Delete components from a specific integration build.

{% code overflow="wrap" lineNumbers="true" %}

```
DELETE /sl-api/v1/agent-apis/integration-builds/{bsid}/components
```

{% endcode %}

### Request Details <a href="#request-details" id="request-details"></a>

#### Request Parameters <a href="#request-parameters.2" id="request-parameters.2"></a>

<table><thead><tr><th width="163.45703125">Parameter</th><th>Description</th></tr></thead><tbody><tr><td>bsid</td><td>Build Session ID</td></tr></tbody></table>

#### Request Body <a href="#request-body.2" id="request-body.2"></a>

Array of build session IDs **or** component details (app name, branch name, build name).\
If both `bsid` and `app-branch-build` are supplied, `app-branch-build` are prioritized.

#### Response Status Codes <a href="#response-status-codes.2" id="response-status-codes.2"></a>

<table><thead><tr><th width="111.8828125">Code</th><th width="140.74609375">Status</th><th>Description</th></tr></thead><tbody><tr><td>200</td><td>OK</td><td>Components successfully updated</td></tr><tr><td>409</td><td>CONFLICT</td><td>Some components are invalid</td></tr></tbody></table>

### Request Samples <a href="#request-samples.2" id="request-samples.2"></a>

{% tabs %}
{% tab title="HTTP" %}

#### Sample HTTP request and response <a href="#sample-http-request-and-response.2" id="sample-http-request-and-response.2"></a>

{% code overflow="wrap" lineNumbers="true" %}

```http
DELETE /sl-api/v1/agent-apis/integration-builds/{bsid}/components HTTP/1.1
Authorization: Bearer {sealights-agent-token}
Content-Type: application/json
[
  {
    "bsid": "component-bsid",
    "appName": "app",
    "branchName": "branch",
    "buildName": "build"
  }
]
HTTP/1.1 200 OK
HTTP/1.1 409 CONFLICT
```

{% endcode %}
{% endtab %}

{% tab title="Shell" %}

#### Sample Shell command and response <a href="#sample-shell-command-and-response-.2" id="sample-shell-command-and-response-.2"></a>

{% code overflow="wrap" lineNumbers="true" %}

```shell
curl -X DELETE "https://$DOMAIN/sl-api/v1/agent-apis/integration-builds/$BSID/components" \
  -H "Authorization: Bearer $SEALIGHTS_AGENT_TOKEN" \
  -H "Content-Type: application/json"  \
  -d "[{\"bsid\":\"component-bsid\",\"appName\":\"app\",\"branchName\":\"branch\",\"buildName\":\"build\"}]"


200 OK

409 CONFLICT 
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Attach Integration Build to a lab from Multiple environments <a href="#attach-integration-build-to-a-lab-from-multiple-environments" id="attach-integration-build-to-a-lab-from-multiple-environments"></a>

Attach integration build to a lab.

{% code overflow="wrap" lineNumbers="true" %}

```
PUT /sl-api/v1/agent-apis/lab-ids/{labId}/integration-build
```

{% endcode %}

### Request Details <a href="#request-details.1" id="request-details.1"></a>

#### Request Parameters <a href="#request-parameters.3" id="request-parameters.3"></a>

<table><thead><tr><th width="165.06640625">Parameter</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td><strong>labId</strong></td><td>Lab Id</td><td>Required</td></tr></tbody></table>

#### Request Body <a href="#request-body.3" id="request-body.3"></a>

<table><thead><tr><th width="169.0078125">Parameter</th><th width="264.11328125">Description</th><th>Required</th></tr></thead><tbody><tr><td><strong>buildName</strong></td><td>Integration build name</td><td>Required one of buildName or bsid</td></tr><tr><td><strong>bsid</strong></td><td>Integration build session id</td><td>Required one of buildName or bsid</td></tr></tbody></table>

#### Response Status Codes <a href="#response-status-codes.3" id="response-status-codes.3"></a>

<table><thead><tr><th width="104.80859375">Code</th><th width="253.74609375">Status</th><th>Description</th></tr></thead><tbody><tr><td>204</td><td>OK</td><td>Components successfully updated</td></tr><tr><td>400</td><td>BAD REQUEST</td><td><p>One of the following reasons:</p><ul><li>Missing parameter labId , bsid or buildName</li><li>LabID provided is not compatible. Attach is allowed only on multi labs</li></ul></td></tr><tr><td>404</td><td>NOT FOUND</td><td><ul><li>labId '{lab-id}' Not Found</li><li>There is no build '{build-name}' for lab '{lab-id}'</li></ul></td></tr><tr><td>500</td><td>INTERNAL SERVER ERROR</td><td> </td></tr></tbody></table>

### Request Samples  <a href="#request-samples.3" id="request-samples.3"></a>

{% tabs %}
{% tab title="HTTP" %}

#### Sample HTTP request and response <a href="#sample-http-request-and-response.3" id="sample-http-request-and-response.3"></a>

{% code overflow="wrap" lineNumbers="true" %}

```http
PUT /sl-api/v1/agent-apis/lab-ids/{labId}/integration-build HTTP/1.1
Authorization: Bearer {slagent-token}
Accept: application/json
Content-Type: application/json

{
  "buildName": "{build-name}"
}

HTTP/1.1 200 OK
HTTP/1.1 400 BAD REQUEST
HTTP/1.1 404 NOT FOUND
HTTP/1.1 500 INTERNAL SERVER ERROR
```

{% endcode %}
{% endtab %}

{% tab title="Shell" %}

#### Sample Shell command and response <a href="#sample-shell-command-and-response-.3" id="sample-shell-command-and-response-.3"></a>

{% code overflow="wrap" lineNumbers="true" %}

```shell
curl -X PUT "https://$DOMAIN/sl-api/v1/agent-apis/lab-ids/$SL_LABID/integration-build" \
  -H "Authorization: Bearer $SEALIGHTS_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "bsid": "123456789" }'  
  
204 OK
400 BAD REQUEST
404 NOT FOUND
500 INTERNAL SERVER ERROR
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Create integration build lab <a href="#create-integration-build-lab" id="create-integration-build-lab"></a>

Integration build labs are normally created through the UI although they can be created also using the following API:

{% hint style="info" %}
`POST /sl-api/v1/agent-apis/lab-ids`
{% endhint %}

### Request details <a href="#request-details.2" id="request-details.2"></a>

#### Request Body <a href="#request-body.4" id="request-body.4"></a>

<table><thead><tr><th width="149">Parameter</th><th width="486.35546875">Description</th><th>Required</th></tr></thead><tbody><tr><td><strong>appName</strong></td><td>Application name</td><td>Required</td></tr><tr><td><strong>branchName</strong></td><td>Release or Environment name</td><td>Required</td></tr><tr><td>testEnv</td><td>If multiple test environments for the same deployment exist, they can be specified separately</td><td> </td></tr><tr><td>labAlias</td><td>Alias name for the lab</td><td> </td></tr><tr><td>cdOnly</td><td>If true, the integration build gets created automatically when tests are run against the lab</td><td> </td></tr><tr><td>isHidden</td><td>Hide the build lab from the UI</td><td> </td></tr></tbody></table>

#### Response Status Codes <a href="#response-status-codes.4" id="response-status-codes.4"></a>

<table data-header-hidden><thead><tr><th width="140.44140625">Code</th><th width="278.953125">Status</th><th>Description</th></tr></thead><tbody><tr><td>201</td><td>OK</td><td>Response with labId</td></tr><tr><td>400</td><td>Bad request</td><td>Missing parameters</td></tr><tr><td>500</td><td>INTERNAL SERVER ERROR</td><td> </td></tr></tbody></table>

### Request Samples  <a href="#request-samples.4" id="request-samples.4"></a>

{% tabs %}
{% tab title="HTTP" %}

#### Sample HTTP request and response <a href="#sample-http-request-and-response.4" id="sample-http-request-and-response.4"></a>

{% code overflow="wrap" lineNumbers="true" %}

```http
POST /sl-api/v1/agent-apis/lab-ids HTTP/1.1
Authorization: Bearer {sealights-agent-token}
Content-Type: application/json

{
    "appName": "My Product",
    "branchName": "qa",
}

HTTP/1.1 200 OK
HTTP/1.1 409 CONFLICT
```

{% endcode %}
{% endtab %}

{% tab title="Shell" %}

#### Sample Shell command and response <a href="#sample-shell-command-and-response-.4" id="sample-shell-command-and-response-.4"></a>

{% code overflow="wrap" lineNumbers="true" %}

```sh
curl -X POST "https://$DOMAIN/sl-api/v1/agent-apis/lab-ids" \
  -H "Authorization: Bearer $SEALIGHTS_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"appName\":\"My Product\",\"branchName\":\"qa\"}"
  
201 OK
400 BAD REQUEST
500 INTERNAL SERVER ERROR 
```

{% endcode %}
{% endtab %}
{% endtabs %}