Table of contents

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 Solution 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 Solution 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 Solution Studio on the configured Solution service (for example from JavaScript)

function callSkybowPublishAPI() {
  var data = {
    "FirstName": "Peter",
    "LastName": "Muster",
    "UserId": "1111111133333",
    "ServiceName": "YourSolution",
    "CompanyID": "11213231231231",
    "CompanyName": "Test Inc.",
    "SiteUrl": "https://<customerTenant>.sharepoint.com/sites/<customerSite>",
    "SiteLoginName": "janesmith@<customerTenant>.onmicrosoft.com",
    "SiteLoginPassword": "<site password>",
    "Email": "<customer Email address>",
    "Callback": ""
  };
  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
  });
}

To try it out see the Pen skybow Solutions Provisioning API by skybow (@skybow) on CodePen.

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 Solution Studio (i.e. "https://skybowsolutionmanager.azurewebsites.net/api/cb40d74f-1105-e811-80c2-00155d0ae8ad/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:

• FirstName, LastName, UserId, CompanyID, CompanyName refer to the customer.
• 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.

skybow Solutions Foundation add-in (download) 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.skybow.com/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"
 }
 ],
 "customerData": {
 "phone": "Optional",
 "postalCode": "Optional",
 "address": "Optional Customer Address",
 "country": "Optional",
 "city": "Optional",
 "customerEmail": "Optional",
 "email": "Optional",
 "companyID": "Required",
 "companyName": "Optional"
 },
 "callbackUrl": "http://your.site.url"
 }

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}]

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".

"companyID" value in the request can be any number. It's used in Solution Studio API Deployments tab: batch deployments are grouped by "companyID", "companyName" is displayed as a node.

Solution update process

When the deployed package needs to be updated, update it in the Solution 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 Solution 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.