Note: To use the Teamsware API deployment check your tenant settings and allow custom app authentication as described here

What is API deployment

API deployment is a type of publishing, that allows starting deployment process with HTTP call

Registering solution service

After successful packaging your Solution a new service can be registered.
Clicking the Publish button on Publish tab opens the wizard that guides you through defining a service for publishing this Solution.

After accepting the terms and conditions, the following Service Details need to be specified:

• Service Title: The title as it will appear in Teamsware Studio.
• Description: A description of the service.
• Solution Package: Package of the solution that will be provided. The latest package version is selected by default.
• Authentication credentials: Credentials for validating requests -> this can be any username/password combination.

After the service has been registered in Teamsware Studio, the external system needs to be configured correctly to call the Solution Management API.

The request URLs for creating, deleting and modifying the deployment are displayed in the General Settings of a registered service.

These URLs can be used as requests to Solution Management API initiated by external service. 

Calling Provisioning API directly from code

The API can be called directly by posting to the URL provided in Teamsware Studio on the configured Solution service (for example from JavaScript)

function callTeamswarePublishAPI() {
  var data = {
    "SiteUrl": "https://<customerTenant>.sharepoint.com/sites/<customerSite>",
    "SiteLoginName": "janesmith@<customerTenant>.onmicrosoft.com",
    "SiteLoginPassword": "<site password>",
    "Email": "Optional",
    "Callback": "http://your.site.url"
  };
  jQuery.support.cors = true;
  jQuery.ajax({
    method: "POST",
    url: serviceUrl,
    crossOrigin: true,
    dataType: "json",
    beforeSend: function(xhr) {
      xhr.setRequestHeader(
        "Authorization",
        "Basic " + btoa(serviceUser + ":" + servicePassword)
      );
    },
    data: data
  });
}

Notes:

- Make sure to pass a valid email address in the Email parameter. Confirmations and errors are sent to the given email address.

- The serviceUrl variable for the ajax call should be the URL provided on the service by Teamsware Studio (i.e. https://solutionmanager.teamsware.app/api/8f499960-00da-ed11-8aae-14cb652751b2/provision" ).

- Set the variables serviceUser and servicePassword to the appropriate values entered on creating the service.

- In data a JSON with the parameters should be set according to the deployment:

• The SiteUrl is the URL of the SharePoint site the solution needs to be deployed to.
• The SiteLoginName and SiteLoginPassword refer to the SharePoint user with admin rights to the site.
• Email will be set to the customers email address so that he will receive notifications on the status of the deployment.
• Callback can be any URL to a site where a POST request will be done when the solution has been deployed. For successful deployments the body of the post will be "{status: "Completed", errorDetails: null}. When deployments fail the body will be {status: "Failed", errorDetails: "<some error details>"}. It is optional to provide the Callback parameter.

API endpoint for batch deployment

We have implemented automatic provisioning using our tenant wide permissions foundation add-in that gives permissions to Background Accelerators used in deployed solutions.

Teamsware Solutions Foundation add-in should be installed only once per tenant in the global app catalog. When it is trusted and scripting capabilities on the target site collections are enabled, the provisioning can be started.

The following POST API can be used to start new deployments:

Post
https://solutionmanager.teamsware.app/api/provision

Authotization
Credentials ("Basic username:userpassword" in base64 string)

Headers
Content-Type: application/json
Authorization: Basic aXJhOmlyYQ==

Body
{
 "serviceData": [{
 "serviceId": "60366197-9088-ea11-86e9-000d3a222298",
 "webUrl": "https://m365b601773.sharepoint.com/Lunches"
 },
 {
 "serviceId": "60366197-9088-ea11-86e9-000d3a222298",
 "webUrl": "https://m365b601775.sharepoint.com/Lunches"
 }
 ],
 "email": "Optional",
 "callbackUrl": "http://your.site.url",
 "callbackHeaderName": "Key1,Key2",
 "callbackHeaderValue": "Value1,Value2",
 "statusFieldUpdate": {
   "webUrl":"https://m365x36372584.sharepoint.com/sites/LVOsourceCS",
   "listName":"<internal name of List from URL>", (or "ListId":"d1620f67-de02-4b75-a848-a988ef85b689")
   "fieldName":"Status",
   "itemId": "Id"
   }
 }

Response example
[{"Provision":{"ServiceId":"60366197-9088-ea11-86e9-000d3a222298","WebUrl":"https://m365b601773.sharepoint.com/Lunches"},"Status":"Completed","ErrorMessage":null},{"Provision":{"ServiceId":"60366197-9088-ea11-86e9-000d3a222298","WebUrl":"https://m365b601775.sharepoint.com/Lunches"},"Status":"Completed","ErrorMessage":null}]

Status field configuration during deployment process

Additionally, you can extend Body of your request with status field configuration parameter "statusFieldUpdate". The "statusFieldUpdate" parameter with listName (alternative ListId can be used), internal fieldname (single line of text or choice field type) and itemId will display the current status according to the deployment process status and can be able to be configured e.g. Triggered actions on this list. 

Possible status:
In progress - set when first deployment in Batch starts
Completed - when last deployment finished
Failed - if any on deployment failed (also set when last deployment finished)
Note: Cross-tenant status field update is not allowed.

When service definition is created, the definition ID can be copied (as a part of service URL).
This service definition ID is used in the request as "serviceId".

Batch deployments in Teamsware Studio API Deployments tab are grouped by Tenant URL.

Solution update process

When the deployed package needs to be updated, update it in the Teamsware Studio API Deployments tab: firstly service definition and afterwards - deployment itself.

An email with the update status is sent when update process is completed.

Batch update can be done in a following way: service definition from the Teamsware Studio API Deployments tab should be updated and afterwards the batch provisioning API should be called. In this case the deployment is overwritten to the newer package version.