Introduction

IBM Cloud Schematics delivers Terraform-as-a-Service so that you can use a high-level scripting language to model the resources that you want in your IBM Cloud environment, and enable Infrastructure as Code (IaC). Terraform is an Open Source software that is developed by HashiCorp that enables predictable and consistent resource provisioning to rapidly build complex, multi-tier cloud environments.

IBM Cloud Schematics and Ansible are the complementary solutions, where Ansible helps you to provision use case, config management, and deploy a secured application. IBM Cloud Schematics also supports Ansible Galaxy to streamline your automation tasks by using roles and collections.

The code examples on this tab use the IBM Cloud Schematics SDK for Java.

Gradle

compile group: 'com.ibm.cloud', name: 'schematics', version: '0.+'

Maven

GitHub

The code examples on this tab use the IBM Cloud Schematics SDK for Node.js.

Installation

npm install --save @ibm-cloud/schematics

GitHub

The code examples on this tab use the IBM Cloud Schematics SDK for Python.

Installation

pip3 install ibm-schematics

GitHub

The code examples on this tab use the IBM Cloud Schematics SDK for Go.

Installation

go get -u github.com/IBM/schematics-go-sdk 

GitHub

Before you begin

Authentication

The IBM Cloud Schematics API uses Identity and Access Management (IAM) to authenticate requests. Pass a bearer token in an Authorization header or an apikey. Tokens support authenticated requests without embedding service credentials in every call. API keys use basic authentication. For more information, see IAM access.

Authentication with external configuration

In this scenario, configuration is defined with an external credentials file and authenticator constructed by SDK's authenticator factory during client initialization. This avoids hard-coding credentials within application code.

The default name of the credentials file is ibm-credentials.env. It is expected to be located in either the current directory or in the user's home directory. The path and name of the file can be controlled using the IBM_CREDENTIALS_FILE environment variable.

The name of each configuration property contains the service name along with the actual attribute name in the form <service-name>_<attribute-name>.

It is not necessary to use a .env file, these properties can be set using environment variables with the same name in the environment where the application will be executed.

Variable guide for the authentication code samples

`{apikey}` IAM API key
`{url}` URL of Schematics instance

SDK managing the IAM token. Replace {apikey} and {url}.

IBM_SCHEMATICS_URL={url}
IBM_SCHEMATICS_APIKEY={apikey}
import com.ibm.cloud.schematics.v1.Schematics;

Schematics service = Schematics.newInstance("ibm-schematics");
const { SchematicsV1 } = require('@ibm-cloud/schematics');

const service = SchematicsV1.newInstance({
    serviceName: 'ibm-schematics'
});
from ibm_schematics.schematics_v1 import SchematicsV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

service = SchematicsV1.new_instance(service_name="ibm-schematics")
import (
    "github.com/IBM/schematics-go-sdk/schematicsv1"
)
schematicsService, err := schematicsv1.NewSchematicsV1UsingExternalConfig(&schematicsv1.SchematicsV1Options{
    ServiceName: "ibm-schematics",
})

Programmatic authentication

In this scenario authentication configured by constructing an authenticator instance supplying configuration attributes programmatically and then passing this instance to a client instantiator.

SDK managing the IAM token.

import com.ibm.cloud.schematics.v1.Schematics;
import com.ibm.cloud.sdk.core.security.IamAuthenticator;

IamAuthenticator authenticator = new IamAuthenticator("{apikey}");

Schematics service = new Schematics(Schematics.DEFAULT_SERVICE_NAME, authenticator);

service.setServiceUrl("{url}");
const { SchematicsV1 } = require('@ibm-cloud/schematics');
const { IamAuthenticator } = require('ibm-cloud-sdk-core');

const authenticator = new IamAuthenticator({
    apikey: '{apikey}'
});

const service = new SchematicsV1({
    authenticator: authenticator
});

service.setServiceUrl('{url}');
from ibm_schematics.schematics_v1 import SchematicsV1
from ibm_cloud_sdk_core.authenticators import IAMAuthenticator

authenticator = IAMAuthenticator('{apikey}')

service = SchematicsV1(authenticator=authenticator)

service.set_service_url('{url}')
import (
    "github.com/IBM/go-sdk-core/v4/core"
    "github.com/IBM/schematics-go-sdk/schematicsv1"
)
authenticator := &core.IamAuthenticator{
    ApiKey: "{apikey}",
}
schematicsv1.NewSchematicsV1(
    &schematicsv1.SchematicsV1Options{
        URL:           "{url}",
        Authenticator: authenticator,
    }
)

Authorization

To use the IBM Cloud Schematics API, you must be authorized to work with IBM Cloud Schematics. Schematics uses service access roles in Identity and Access Management (IAM) to determine the permissions that you have in Schematics. For more information about required permissions, see Managing user access.

If you are assigned an IBM Cloud Schematics service access role, you can view, create, update, delete, or run an action against your workspaces in Schematics. To provision the IBM Cloud resources that you defined in your Terraform template, you must be assigned the IAM platform or service access role that is required to provision the individual resource. For example, to provision an IBM Cloud Kubernetes Service cluster, you must have the Administrator platform role and the Manager service access role for IBM Cloud Kubernetes Service in addition to the permissions in IBM Cloud Schematics. Refer to the documentation for your resource to determine the access policies that you need to provision and work with your resource.

API endpoints

IBM Cloud Schematics provides different APIs that you can use to create and work with workspaces in specific locations. The API endpoint determines where your Schematics actions run and where your workspace data is stored. By default, al information that is stored in Schematics is encrypted in transit and at rest. To ensure disaster recovery, your data is replicated to another location within the same geography. Make sure that your data can be stored in these regions before you start using Schematics.

Location API endpoint Location where Schematics actions run Data is stored in Data is replicated to
North America Public: https://us.schematics.cloud.ibm.com

Private: https://private-us-.schematics.cloud.ibm.com (Deprecated)
IBM Cloud Schematics actions run in either the us-south or us-east location. Workspaces that are created with this endpoint and all associated data are stored in the US. Data is replicated between two locations in the US.
Dallas Public: https://us-south.schematics.cloud.ibm.com

Private: https://private-us-south.schematics.cloud.ibm.com
All IBM Cloud Schematics actions run in the Dallas (us-south) location. All workspaces are stored in the Dallas (us-south) location. Data is replicated between two locations in the US for disaster recovery purposes.
Washington Public: https://us-east.schematics.cloud.ibm.com

Private: https://private-us-east.schematics.cloud.ibm.com
All IBM Cloud Schematics actions run in the Washington (us-east) location. All workspaces are stored in the Washington (us-east) location. Data is replicated between two locations in the US for disaster recovery purposes.
Europe Public: https://eu.schematics.cloud.ibm.com

Private: https://private-eu-.schematics.cloud.ibm.com (Deprecated)
IBM Cloud Schematics actions run in either the eu-de or eu-gb location. Workspaces that are created with this endpoint and all associated data are stored in Europe. Data is replicated between two locations in Europe.
Frankfurt Public: https://eu-de.schematics.cloud.ibm.com

Private: https://private-eu-de.schematics.cloud.ibm.com
All IBM Cloud Schematics actions run in the Frankfurt (eu-de) location. All workspaces are stored in the Frankfurt (eu-de) location. Data is replicated between two locations in Europe for disaster recovery purposes.
London Public: https://eu-gb.schematics.cloud.ibm.com

Private: https://private-eu-gb.schematics.cloud.ibm.com
All IBM Cloud Schematics actions run in the London (eu-gb) location. All workspaces are stored in the London (eu-gb) location. Data is replicated between two locations in Europe for disaster recovery purposes.

Versioning

All API requests require a major version in the path (/v1/).

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response always indicates success. A 400 type response is some sort of failure, and a 500 type response usually indicates an internal system error.

HTTP error code Description Recovery
200 Success The request was successful.
400 Bad Request The input parameters in the request body are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized to access '{workspace}'. Check that you have the correct access credentials and permissions.
404 Not Found The requested resource could not be found.
408 Request Timeout The connection to the server timed out. Wait a few minutes, then try again.
409 Conflict The entity is already in the requested state.
429 Too Many Requests Too many requests have been made within a time window. Wait before calling the API again.
500 Internal Server Error IBM Cloud Schematics is currently unavailable. Your request could not be processed. Please wait a few minutes and try again. If you still encounter this problem, note the incident ID and contact IBM Cloud support.
503 Service Temporarily Unavailable IBM Cloud Schematics could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

Code example

In the case of an error response from the server endpoint, the Java SDK will throw an exception from the com.ibm.cloud.sdk.core.service.exception package. The base class for all exception classes is ServiceResponseException - that derives from unchecked RuntimeException - to handle any error response from the server. Here is a list about predefined exceptions and their corresponding statusCode and message content.

Exception Status Code and default error message
ServiceResponseException Base class for all exceptions
BadRequestException 400 Bad Request
UnauthorizedException 401 Unauthorized
ForbiddenException 403 Forbidden
NotFoundException 404 Not found
ConflictException 409 Conflict
UnsupportedException 415 Unsupported media type
InternalServerErrorException 500 Internal server error
IllegalArgumentException An invalid argument was passed to the method.

All service exceptions contain the following fields:

Field Description
statusCode HTTP response status code
message the error message returned in the response
debuggingInfo a Map<String, Object> which contains the unmarshalled error response object in the event that a JSON error response is returned.
This will provide more information beyond the error message.

Example error handling

import com.ibm.cloud.sdk.core.service.exception.BadRequestException;
import com.ibm.cloud.sdk.core.service.exception.NotFoundException;
import com.ibm.cloud.sdk.core.service.exception.ServiceResponseException;
import com.ibm.cloud.sdk.core.service.exception.UnauthorizedException;

try {
  // Invoke a Schematics method request
} catch (BadRequestException e) {
  // Handle Bad Request (400) exception
} catch (UnauthorizedException e) {
  // Handle Unauthorized (401) exception
} catch (NotFoundException e) {
  // Handle Not Found (404) exception
} catch (ServiceResponseException se) {
  System.out.println("Service returned status code "
    + se.getStatusCode() + ": " + se.getMessage());
  System.out.println("Detailed error info: " + se.getDebuggingInfo().getOrDefault("reason", "")););
} catch (RuntimeException re) {
  // Handle other error conditions
  System.out.println("Unexpected Exception: \n" + re.getMessage());
}

Code example

In the case of an error response from the server endpoint, the Node SDK will create an Error object that contains either the HTTP response error message or a generic error message. In case of network problems the axios package will generate an Error object. This Error object is passed as the first parameter to the callback function, its failure describing content is as shown in the following table.

Field Description
status HTTP response status code
statusText a text description of the status code
message generic error message
body the error response body as text

Example error handling

service.<Schematics API Method Request>(params)
  .then((response) => {
    // ...handle successful response...
  })
  .catch(error => {
    console.log("Error status code: " + error.status);
    console.log("Error status text: " + error.statusText);
    console.log("Error message:     " + error.message);
    console.log("Error details:     " + error.body)
  });

Code example

In the case of an error response from the server endpoint, the Python SDK will throw an ApiException that includes more information about the cause of the failure. It provides the following details:

Field Description
code HTTP response status code
message the error message returned in the response
reason a more detailed description about the cause of the failure

Example error handling

from ibm_cloud_sdk_core import ApiException

try:
  # Invoke a Schematics method request
except ApiException as ae:
  print("Method failed")
  print(" - status code: " + str(ae.code))
  print(" - error message: " + ae.message)
  if ("reason" in ae.http_response.json()):
    print(" - reason: " + ae.http_response.json()["reason"])


from requests import ConnectionError, ReadTimeout, RequestException

try:
  # Invoke a Schematics method request
except ConnectionError as cerr:
  print("Connection error occurred:")
  print(cerr)
except ReadTimeout as rt:
  # The server did not send any data in the allotted amount of time.
  print("Read timed out:")
  print(rt)
except RequestException as re:
  # Handle other request failures
  print("Request Exception:")
  print(re)

Code example

In the case of an error response from the server endpoint, the Go SDK will create an error object that contains either the HTTP response error message or a generic error message.

An additional detailedResponse will be returned by the service that will contain the following fields:

Field Description
StatusCode HTTP response status code
Result JSON error response object unmarshalled as map[string]interface{}
RawResult raw non-JSON error response object as []byte

Example error handling

_, detailedResponse, err := // Invoke a Schematics method request
if err != nil {
    if (detailedResponse != nil) {
      fmt.Println("Error status code: ", detailedResponse.StatusCode)
      fmt.Println("Error message:     ", err.Error())
      errorMap, ok := detailedResponse.GetResultAsMap(); if ok {
        fmt.Println("Reason:          ", errorMap["reason"])
      }
    } else {
      // Handle other error conditions
      fmt.Println("Error message: ", err.Error())
    }
  }

Methods

List supported schematics locations

Retrieve a list of IBM Cloud locations where you can create the Schematics workspace or action. workspaces.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v1/locations

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • curl -X GET https://schematics.cloud.ibm.com/v1/locations -H "Authorization: <iam_token>"
  • getSchematicsLocationOptions := schematicsService.NewListSchematicsLocationOptions()
    
    locations, detailedResponse, err := schematicsService.ListSchematicsLocation(getSchematicsLocationOptions)
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(locations, "", "  ")
    fmt.Println(string(w))
  • schematicsService.listSchematicsLocation({})
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • list_schematics_locations = schematics_service.list_schematics_location().get_result()
    
    print(json.dumps(list_schematics_locations, indent=2))
  • ListSchematicsLocationOptions listSchematicsLocationOptions = new ListSchematicsLocationOptions();
    
    Response<List<SchematicsLocations>> response = service.listSchematicsLocation(listSchematicsLocationOptions).execute();
    List<SchematicsLocations> listSchematicsLocations = response.getResult();
    
    System.out.println(listSchematicsLocations);

Response

A list of the IBM Cloud locations where you can create the Schematics workspace or action.

Status Code

  • Successfully returned the location information.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

Example responses
  • {
      "ID": "us",
      "Name": "us",
      "Country": "",
      "Geography": "na",
      "Kind": "country",
      "Metro": "",
      "MultizoneMetro": ""
    }

List supported locations

Retrieve a list of IBM Cloud locations where you can work with the Schematics objects.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v2/locations

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • curl --location --request GET  https://schematics.cloud.ibm.com/v2/locations --header "Authorization: <access_token> " --header "Content-Type: application/json" --header "X-Feature-Region-Visibility: true"
  • schematics_locations_list = schematics_service.list_locations(headers={'X-Feature-Region-Visibility' : 'true'}).get_result()
    print(json.dumps(schematics_locations_list, indent=2))
    
  • ListLocationsOptions listLocationsOptions = new ListLocationsOptions();
    service.setDefaultHeaders(Collections.singletonMap("X-Feature-Region-Visibility", "true"));
    Response<SchematicsLocationsList> response3 = service.listLocations(listLocationsOptions).execute();
    SchematicsLocationsList schematicsLocationsList = response3.getResult();
    System.out.println(schematicsLocationsList);
    
  • const header = {
    "X-Feature-Region-Visibility":"true",
    }
    const params = {
    headers : header
    };
    schematicsService.listLocations(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
    
  • listLocationsOptions := schematicsService.NewListLocationsOptions()
    schematicsLocationsList, response, err := schematicsService.ListLocations(listLocationsOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(schematicsLocationsList, "", "  ")
    fmt.Println(string(b))
    fmt.Println(response)
    

Response

The list of locations details.

Status Code

  • Successfully listed all the locations.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "locations": [
        {
          "region": "eu-de",
          "metro": "Frankfurt",
          "geography_code": "eu",
          "geography": "Europe",
          "country": "Germany",
          "type": "mzr",
          "paired_region": [
            "eu-gb"
          ],
          "restricted": true
        },
        {
          "region": "eu-gb",
          "metro": "London",
          "geography_code": "eu",
          "geography": "Europe",
          "country": "United Kingdom",
          "type": "mzr",
          "paired_region": [
            "eu-de"
          ],
          "restricted": true
        },
        {
          "region": "us-east",
          "metro": "Washington DC",
          "geography_code": "NA",
          "geography": "North America",
          "country": "United States",
          "type": "mzr",
          "paired_region": [
            "us-south"
          ],
          "restricted": false
        },
        {
          "region": "us-south",
          "metro": "Dallas",
          "geography_code": "NA",
          "geography": "North America",
          "country": "United States",
          "type": "mzr",
          "paired_region": [
            "us-east"
          ],
          "restricted": false
        }
      ]
    }

List resource groups

Retrieve a list of IBM Cloud resource groups that your account has access to.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v1/resource_groups

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • curl -X GET https://schematics.cloud.ibm.com/v1/resource_groups -H "Authorization: <iam_token>"
  • listResourceGroupOptions := schematicsService.NewListResourceGroupOptions()
    
    resourceGroups, detailedResponse, err := schematicsService.ListResourceGroup(listResourceGroupOptions)
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(resourceGroups, "", "  ")
    fmt.Println(string(w))
  • schematicsService.listResourceGroup({})
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • list_resource_group_response = schematics_service.list_resource_group().get_result()
    
    print(json.dumps(list_resource_group_response, indent=2))
  • ListResourceGroupOptions listResourceGroupOptions = new ListResourceGroupOptions();
    
    Response<List<ResourceGroupResponse>> response = service.listResourceGroup(listResourceGroupOptions).execute();
    List<ResourceGroupResponse> listResourceGroupResponse = response.getResult();
    
    System.out.println(listResourceGroupResponse);

Response

A list of resource groups that your account has access to.

Status Code

  • Successfully returned resource groups information.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

No Sample Response

This method does not specify any sample responses.

Get Schematics API information

Retrieve detailed information about the IBM Cloud Schematics API version and the version of the provider plug-ins that the API uses.

GET /v1/version

Request

No Request Parameters

This method does not accept any request parameters.

  • curl -X GET https://schematics.cloud.ibm.com/v1/version
  • schematicsVersion, detailedResponse, err := schematicsService.GetSchematicsVersion(&schematicsv1.GetSchematicsVersionOptions{})
    if err != nil {
      panic(err)
    }
    
    b, _ := json.MarshalIndent(schematicsVersion, "", "  ")
    fmt.Println(string(b))
    
  • schematicsService.getSchematicsVersion({})
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • version_response = schematics_service.get_schematics_version().get_result()
    
    print(json.dumps(version_response, indent=2))
  • GetSchematicsVersionOptions getSchematicsVersionOptions = new GetSchematicsVersionOptions();
    
    Response<VersionResponse> response = service.getSchematicsVersion(getSchematicsVersionOptions).execute();
    VersionResponse versionResponse = response.getResult();
    
    System.out.println(versionResponse);

Response

Successful response when you retrieve detailed information about the IBM Cloud Schematics API.

Status Code

  • Successfully returned version information.

Example responses
  • {
      "commitsha": "f905818892a0fa73d6b74792cfeabd0b49aeb930",
      "builddate": "2019-11-01T07:06:27.000Z",
      "buildno": "3230",
      "terraform_version": "v0.12.24",
      "terraform_provider_version": "v0.18.0",
      "helm_version": "v2.14.2",
      "helm_provider_version": "v0.10.0"
    }

Get variable metadata by parsing the template

Get the variable metadata from the template. This metadata can be passed in the payload during Schematics workspace create or update API call.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

POST /v2/template_metadata_processor

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • The personal access token to authenticate with your private GitHub or GitLab repository and access your Terraform template.

Create template metadata request.

  • curl --location --request POST https://schematics.cloud.ibm.com/v2/template_metadata_processor --header "Authorization: <access_token> " --header " Content-Type: application/json" --data-raw "{"region":"us-east","template_type": "terraform_v0.15","source": [{"source_type": "git_hub",[{"git": "computed_git_repo_url": "string", "git_repo_url": "https://github.com/IBM-Cloud/terraform-provider-ibm/tree/master/examples/ibm-vsi","git_repo_folder": ".", "git_release": "latest", "git_branch": "master"}]}] "source_type": "git_hub"
  • external_source_model = {
    'source_type': 'git_hub',
    'git' : {
    'computed_git_repo_url': 'string',
    'git_repo_url': 'https://github.com/IBM-Cloud/terraform-provider-ibm/tree/master/examples/ibm-vsi',
    },
    }
    template_meta_data_response = schematics_service.process_template_meta_data(
    template_type='terraform_v0.15',
    source=external_source_model
    ).get_result()
    print(json.dumps(template_meta_data_response, indent=2))
    
  • ExternalSource externalSourceModel = new ExternalSource.Builder()
    .sourceType("git_hub")
    .git(new ExternalSourceGit.Builder().gitRepoUrl("https://github.com/IBM-Cloud/terraform-provider-ibm/tree/master/examples/ibm-vsi").build())
    .build();
    ProcessTemplateMetaDataOptions processTemplateMetaDataOptions = new ProcessTemplateMetaDataOptions.Builder()
    .templateType("terraform_v0.12")
    .source(externalSourceModel)
    .region("us-east")
    .build();
    Response<TemplateMetaDataResponse> response = service.processTemplateMetaData(processTemplateMetaDataOptions).execute();
    TemplateMetaDataResponse templateMetaDataResponse = response.getResult();
    System.out.println(templateMetaDataResponse);
    
  • const params = {
    templateType: 'terraform_v0.15',
    source:{
    source_type: "git_hub",
    git:{
    computed_git_repo_url: "string",
    git_repo_url: "https://github.com/IBM-Cloud/terraform-provider-ibm/tree/master/examples/ibm-vsi",
    git_repo_folder: ".",
    git_release: "latest",
    git_branch: "master"
    }
    },
    source_type: "git_hub"
    };
    schematicsService.processTemplateMetaData(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
    
  • externalSourceModel := &schematicsv1.ExternalSource{
    SourceType: core.StringPtr("local"),
    }
    processTemplateMetaDataOptions := schematicsService.NewProcessTemplateMetaDataOptions(
    "testString",
    externalSourceModel,
    )
    processTemplateMetaDataOptions.SetTemplateType("terraform_v0.12")
    source := &schematicsv1.ExternalSource{
    SourceType: core.StringPtr("git_hub"),
    Git: &schematicsv1.ExternalSourceGit{
    ComputedGitRepoURL: core.StringPtr("string"),
    GitRepoURL:         core.StringPtr("https://github.com/IBM-Cloud/terraform-provider-ibm/tree/master/examples/ibm-vsi"),
    },
    }
    processTemplateMetaDataOptions.SetSource(source)
    processTemplateMetaDataOptions.SetRegion("us-east")
    processTemplateMetaDataOptions.SetSourceType("git_hub")
    templateMetaDataResponse, response, err := schematicsService.ProcessTemplateMetaData(processTemplateMetaDataOptions)
    if err != nil {
    fmt.Println(err)
    }
    b, _ := json.MarshalIndent(templateMetaDataResponse, "", "  ")
    fmt.Println(string(b))
    fmt.Println(response)
    

Response

Template metadata response

Status Code

  • Successfully processed the template.

  • Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "type": "terraform_v0.15",
      "variables": [
        {
          "name": "softlayer_username",
          "metadata": {
            "type": "string",
            "description": "Enter your IBM Infrastructure (SoftLayer) full username, you can get this using: https://control.bluemix.net/account/user/profile"
          }
        },
        {
          "name": "softlayer_api_key",
          "metadata": {
            "type": "string",
            "description": "Enter your IBM Infrastructure (SoftLayer) API key, you can get this using: https://control.bluemix.net/account/user/profile"
          }
        }
      ]
    }

List workspaces

Retrieve a list of Schematics workspaces from your IBM Cloud account that you have access to. The list of workspaces that is returned depends on the API endpoint that you use. For example, if you use an API endpoint for a geography, such as North America, only workspaces that are created in us-south or us-east are returned.

For more information about supported API endpoints, see API endpoints.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v1/workspaces

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.list

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Query Parameters

  • The starting position of the item in the list of items. For example, if you have three workspaces in your account, the first workspace is assigned position number 0, the second workspace is assigned position number 1, and so forth. If you have 6 workspaces and you want to list the details for workspaces 2-6, enter 1. To limit the number of workspaces that is returned, use the limit option in addition to the offset option. Negative numbers are not supported and are ignored.

    Possible values: value ≥ 0

  • The maximum number of items that you want to list. The number must be a positive integer between 1 and 2000. If no value is provided, 100 is used by default.

    Possible values: 1 ≤ value ≤ 2000

    Default: 100

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces -H "Authorization: <iam_token>"
  • listWorkspacesOptions := schematicsService.NewListWorkspacesOptions()
    
    workspaceList, detailedResponse, err := schematicsService.ListWorkspaces(listWorkspacesOptions)
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(workspaceList, "", "  ")
    fmt.Println(string(w))
  • schematicsService.listWorkspaces({})
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • workspace_response_list = schematics_service.list_workspaces().get_result()
    
    print(json.dumps(workspace_response_list, indent=2))
  • ListWorkspacesOptions listWorkspacesOptions = new ListWorkspacesOptions.Builder()
    .build();
    
    Response<WorkspaceResponseList> response = service.listWorkspaces(listWorkspacesOptions).execute();
    WorkspaceResponseList workspaceResponseList = response.getResult();
    
    System.out.println(workspaceResponseList);

Response

List of workspaces

Status Code

  • Successfully listed the workspaces that you have access to.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "offset": 0,
      "limit": 1,
      "count": 6,
      "workspaces": [
        {
          "id": "us-east.workspace.testWorkspaceApi.bb026f5e",
          "name": "testWorkspaceApi",
          "crn": "crn:v1:staging:public:schematics:us-south:a/0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0:00000000-0000-0000-0000-00000000000:workspace:us-east.workspace.testWorkspaceApi.bb026f5e",
          "type": [
            "terraform_v0.12"
          ],
          "description": "terraform workspace",
          "resource_group": "",
          "location": "us-east",
          "tags": [
            "department:HR",
            "application:compensation",
            "environment:staging"
          ],
          "created_at": "2021-09-28T11:34:22.881Z",
          "created_by": "schematics@ibm.com",
          "status": "DRAFT",
          "failure_reason": "",
          "workspace_status_msg": {
            "status_code": "",
            "status_msg": ""
          },
          "workspace_status": {
            "frozen": true,
            "frozen_by": "schematics@ibm.com",
            "frozen_at": "2021-09-28T11:34:22.306Z",
            "locked": false
          },
          "template_repo": {
            "url": "https://github.com/ptaube/tf_cloudless_sleepy",
            "commit_id": "",
            "full_url": "https://github.com/ptaube/tf_cloudless_sleepy",
            "has_uploadedgitrepotar": false
          },
          "template_data": [
            {
              "id": "6fef745e-dfaa-42",
              "folder": ".",
              "compact": false,
              "type": "terraform_v0.12",
              "values_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/template_data/6fef745e-dfaa-42/values",
              "values": "",
              "variablestore": [
                {
                  "name": "sample_var",
                  "secure": false,
                  "value": "THIS IS IBM CLOUD TERRAFORM CLI DEMO",
                  "type": "",
                  "description": "Description of sample_var"
                },
                {
                  "name": "sleepy_time",
                  "secure": false,
                  "value": "15",
                  "type": "",
                  "description": ""
                }
              ],
              "has_githubtoken": false
            }
          ],
          "runtime_data": [
            {
              "id": "6fef745e-dfaa-42",
              "engine_name": "terraform",
              "engine_version": "v0.12.31",
              "state_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/runtime_data/6fef745e-dfaa-42/state_store",
              "log_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/runtime_data/6fef745e-dfaa-42/log_store"
            }
          ],
          "shared_data": {
            "resource_group_id": ""
          },
          "updated_at": "1901-01-01T00:00:00.000Z",
          "last_health_check_at": "1901-01-01T00:00:00.000Z",
          "cart_id": ""
        }
      ]
    }

Create a workspace

Create an IBM Cloud Schematics workspace that points to the source repository where your Terraform template or the IBM Cloud software template is stored. You can decide to create your workspace without connecting it to a GitHub or GitLab repository. Your workspace is then created with a Draft state. To later connect your workspace to a GitHub or GitLab repository, you must use the PUT /v1/workspaces/{id} API to update the workspace or use the /v1/workspaces/{id}/templates/{template_id}/template_repo_upload API to upload a TAR file instead.

Getting API endpoint:-

  • The Schematics API endpoint that you use to create the workspace determines where your Schematics actions run and your data is stored. See API endpoints for more information.
  • If you use the API endpoint for a geography and not a specific location, such as North America, you can specify the location in your API request body.
  • If you do not specify the location in the request body, Schematics determines your workspace location based on availability.
  • If you use an API endpoint for a specific location, such as Frankfurt, the location that you enter in your API request body must match your API endpoint.
  • You also have the option to not specify a location in your API request body if you use a location-specific API endpoint.

Getting IAM access token :-

  • Before you create Schematics workspace, you need to create the IAM access token for your IBM Cloud Account.
  • To create IAM access token, use export IBMCLOUD_API_KEY=<ibmcloud_api_key> and execute curl -X POST "https://iam.cloud.ibm.com/identity/token" -H "Content-Type= application/x-www-form-urlencoded" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$IBMCLOUD_API_KEY" -u bx:bx. For more information, about creating IAM access token and API Docs, see IAM access token and Create API key.
  • You can set the environment values export ACCESS_TOKEN=<access_token> and export REFRESH_TOKEN=<refresh_token>.
  • You can use the obtained IAM access token in create workspace curl command.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

POST /v1/workspaces

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.create

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • The personal access token to authenticate with your private GitHub or GitLab repository and access your Terraform template.

Input parameter to create the IBM Cloud Schematics workspace.

  • curl --request POST --url https://schematics.cloud.ibm.com/v1/workspaces -H "Authorization: Bearer <access_token>" -d '{"name":"<workspace_name>","type": ["terraform_v0.12"],"location": "<location>","description": "<workspace_description>","resource_group": "<resource_group_ID>","tags": [],"template_repo": {"url": "<source_repo_url>"},"template_data": [{"folder": ".","type": "terraform_v0.12","variablestore": [{"name": "variable_name1","value": "variable_value1"},{"name": "variable_name2","value": "variable_value2"}]}]}'
  • curl --request POST --url https://schematics.cloud.ibm.com/v1/workspaces -H "Authorization: Bearer <access_token>" -d '{"name":"<workspace_name>","type": ["terraform_v0.12"],"location": "<location>","description": "<workspace_description>","resource_group": "<resource_group_ID>","tags": [],"template_repo": {"url": ""},"template_data": [{"folder": ".","type": "terraform_v0.12","variablestore": [{"name": "variable_name1","value": "variable_value1"},{"name": "variable_name2","value": "variable_value2"}]}]}'
  • curl --request POST --url https://schematics.cloud.ibm.com/v1/workspaces -H  Content-Type: application/json Authorization: Bearer <access_token>" -d '{"name":"testWorkspaceApi","type": ["terraform_v0.12"],"description": "terraform workspace","tags":[  "department:HR", "application:compensation","environment:staging"], "template_repo":{"url":"https://github.com/ptaube/tf_cloudless_sleepy" },"workspace_status":{"frozen":true},"template_data":[{   "folder":".","type":"terraform_v0.12","variablestore":[ {"name":"sample_var","secure":false,"value":"THIS IS IBM CLOUD TERRAFORM CLI DEMO", "description":"Description of sample_var"},{   "name":"sleepy_time","value":"15"}]}]}'
  • templateSourceDataRequestModel := &schematicsv1.TemplateSourceDataRequest{
        Folder: core.StringPtr("."),
        Type:   core.StringPtr("terraform_v0.12.20"),
        Variablestore: []schematicsv1.WorkspaceVariableRequest{
            {
                Name:  core.StringPtr("<variable_name1>"),
                Value: core.StringPtr("<variable_value1>"),
            },
            {
                Name:  core.StringPtr("<variable_name2>"),
                Value: core.StringPtr("<variable_value2>"),
            },
        },
    }
    
    templateRepoRequestModel := &schematicsv1.TemplateRepoRequest{
        URL: core.StringPtr("<source_repo_url>"),
    }
    
    createWorkspaceOptions := &schematicsv1.CreateWorkspaceOptions{
        Description:   core.StringPtr("<description>"),
        Name:          core.StringPtr("<workspace_name>"),
        TemplateData:  []schematicsv1.TemplateSourceDataRequest{*templateSourceDataRequestModel},
        TemplateRepo:  templateRepoRequestModel,
        Type:          []string{"terraform_v0.12.20"},
        Location:      core.StringPtr("<location>"),
        ResourceGroup: core.StringPtr("<resource_group>"),
        Tags:          []string{"<tags>"},
    }
    
    workspaceResponse, detailedResponse, err := schematicsService.CreateWorkspace(createWorkspaceOptions)
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(workspaceResponse, "", "  ")
    fmt.Println(string(w))
    
  • const templateSourceDataRequestModel = {
      folder: '.',
      type: 'terraform_v0.12.20',
      variablestore: [
        {
          name: '<variable_name1>',
          value: '<variable_value1>',
        },
        {
          name: '<variable_name2>',
          value: '<variable_value2>',
        }
      ]
    };
    
    const templateRepoRequestModel = {
      url: '<source_repo_url>,
    };
    
    const params = {
      description: '<description>',
      name: '<workspace_name>',
      templateData: [templateSourceDataRequestModel],
      templateRepo: templateRepoRequestModel,
      type: ['terraform_v0.12.20'],
      location: '<location>',
      resourceGroup: '<resource_group>'
      tags: ['<tags>'],
    };
    
    schematicsService.createWorkspace(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • workspace_variable_request_model = {}
    workspace_variable_request_model['name'] = 'variable_name1'
    workspace_variable_request_model['value'] = 'variable_value1'
    
    template_source_data_request_model = {}
    template_source_data_request_model['env_values'] = [{ 'foo': 'bar' }]
    template_source_data_request_model['folder'] = 'testString'
    template_source_data_request_model['type'] = 'testString'
    template_source_data_request_model['variablestore'] = [workspace_variable_request_model]
    
    template_repo_request_model = {}
    template_repo_request_model['url'] = '<source_repo_url>'
    
    
    workspace_response = schematics_service.create_workspace(
        description="<description>", 
        name="<workspace_name>",
        template_data=[template_source_data_request_model],
        template_repo=template_repo_request_model,
        type=['terraform_v0.12.20'],
        location="<location>",
        resource_group="<resource_group>",
        tags=['<tags>'],
    ).get_result()
    
    print(json.dumps(workspace_response, indent = 2))
  • // Construct an instance of the WorkspaceVariableRequest model
    WorkspaceVariableRequest workspaceVariableRequestModel = new WorkspaceVariableRequest.Builder()
    .name("variable_name1")
    .value("variable_value1")
    .build();
    
    // Construct an instance of the TemplateSourceDataRequest model
    TemplateSourceDataRequest templateSourceDataRequestModel = new TemplateSourceDataRequest.Builder()
    .folder(".")
    .type("terraform_v0.12.20")
    .variablestore(new java.util.ArrayList<WorkspaceVariableRequest>(java.util.Arrays.asList(workspaceVariableRequestModel)))
    .build();
    
    // Construct an instance of the TemplateRepoRequest model
    TemplateRepoRequest templateRepoRequestModel = new TemplateRepoRequest.Builder()
    .url("<source_repo_url>")
    .build();
    
    CreateWorkspaceOptions createWorkspaceOptions = new CreateWorkspaceOptions.Builder()
    .description("<description>")
    .name("<workspace_name>")
    .templateData(new java.util.ArrayList<TemplateSourceDataRequest>(java.util.Arrays.asList(templateSourceDataRequestModel)))
    .templateRepo(templateRepoRequestModel)
    .type(new java.util.ArrayList<String>(java.util.Arrays.asList("terraform_v0.12.20")))
    .location("<location>")
    .resourceGroup("<resource_group>")
    .tags(new java.util.ArrayList<String>(java.util.Arrays.asList("<tags>")))
    .build();
    
    Response<WorkspaceResponse> response = service.createWorkspace(createWorkspaceOptions).execute();
    WorkspaceResponse workspaceResponse = response.getResult();
    
    System.out.println(workspaceResponse);

Response

Workspace details

Status Code

  • Successfully created the workspace in IBM Cloud Schematics. Your resources are not provisioned until you use the POST /workspaces/{id}/apply API.

  • Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • The workspace already exists. To find a list of workspaces, use the GET /workspaces API.

  • The workspace is frozen and disabled. Unfreeze the workspace first before you retry the request. Or the Schematics create, update, delete action has not completed. Wait until the create, update, delete, plan, apply, destroy or refresh action completes before you try again.

  • Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

  • IBM Cloud Schematics could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "id": "us-east.workspace.testWorkspaceApi.bb026f5e",
      "name": "testWorkspaceApi",
      "crn": "crn:v1:staging:public:schematics:us-south:a/0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0:00000000-0000-0000-0000-00000000000:workspace:us-east.workspace.testWorkspaceApi.bb026f5e",
      "type": [
        "terraform_v0.12"
      ],
      "description": "terraform workspace",
      "resource_group": "",
      "location": "us-east",
      "tags": [
        "department:HR",
        "application:compensation",
        "environment:staging"
      ],
      "created_at": "2021-09-28T11:34:22.881Z",
      "created_by": "schematics@ibm.com",
      "status": "DRAFT",
      "failure_reason": "",
      "workspace_status_msg": {
        "status_code": "",
        "status_msg": ""
      },
      "workspace_status": {
        "frozen": true,
        "frozen_by": "schematics@ibm.com",
        "frozen_at": "2021-09-28T11:34:22.306Z",
        "locked": false
      },
      "template_repo": {
        "url": "https://github.com/ptaube/tf_cloudless_sleepy",
        "commit_id": "",
        "full_url": "https://github.com/ptaube/tf_cloudless_sleepy",
        "has_uploadedgitrepotar": false
      },
      "template_data": [
        {
          "id": "6fef745e-dfaa-42",
          "folder": ".",
          "compact": false,
          "type": "terraform_v0.12",
          "values_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/template_data/6fef745e-dfaa-42/values",
          "values": "",
          "variablestore": [
            {
              "name": "sample_var",
              "secure": false,
              "value": "THIS IS IBM CLOUD TERRAFORM CLI DEMO",
              "type": "",
              "description": "Description of sample_var"
            },
            {
              "name": "sleepy_time",
              "secure": false,
              "value": "15",
              "type": "",
              "description": ""
            }
          ],
          "has_githubtoken": false
        }
      ],
      "runtime_data": [
        {
          "id": "6fef745e-dfaa-42",
          "engine_name": "terraform",
          "engine_version": "v0.12.31",
          "state_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/runtime_data/6fef745e-dfaa-42/state_store",
          "log_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/runtime_data/6fef745e-dfaa-42/log_store"
        }
      ],
      "shared_data": {
        "resource_group_id": ""
      },
      "updated_at": "1901-01-01T00:00:00.000Z",
      "last_health_check_at": "1901-01-01T00:00:00.000Z",
      "cart_id": ""
    }

Get workspace details

Retrieve detailed information for a workspace in your IBM Cloud account.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v1/workspaces/{w_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.read

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id} -H "Authorization: Bearer <iam_token>"
  • workspaceDetails, detailedResponse, err := schematicsService.GetWorkspace(&schematicsv1.GetWorkspaceOptions{
        WID: <workspace_id>,
    })
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(workspaceDetails, "", "  ")
    fmt.Println(string(w))
  • const params = {
      wId: '<workspace_id>',
    };
    
    schematicsService.getWorkspace(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • workspace_response = schematics_service.get_workspace(
        w_id='<workspace_id>'
    ).get_result()
    
    print(json.dumps(workspace_response, indent=2))
  • GetWorkspaceOptions getWorkspaceOptions = new GetWorkspaceOptions.Builder()
    .wId("<workspace_id>")
    .build();
    
    Response<WorkspaceResponse> response = service.getWorkspace(getWorkspaceOptions).execute();
    WorkspaceResponse workspaceResponse = response.getResult();
    
    System.out.println(workspaceResponse);

Response

Workspace details

Status Code

  • Successfully retrieved details about your workspace.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • Not found. The specified workspace could not be found. Verify that the workspace ID is correct. To list workspaces in your IBM Cloud account, use the GET /v1/workspaces API.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "id": "us-east.workspace.testWorkspaceApi.bb026f5e",
      "name": "testWorkspaceApi",
      "crn": "crn:v1:staging:public:schematics:us-south:a/0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0:00000000-0000-0000-0000-00000000000:workspace:us-east.workspace.testWorkspaceApi.bb026f5e",
      "type": [
        "terraform_v0.12"
      ],
      "description": "terraform workspace",
      "resource_group": "",
      "location": "us-east",
      "tags": [
        "department:HR",
        "application:compensation",
        "environment:staging"
      ],
      "created_at": "2021-09-28T11:34:22.881Z",
      "created_by": "schematics@ibm.com",
      "status": "INACTIVE",
      "failure_reason": "",
      "workspace_status_msg": {
        "status_code": "200",
        "status_msg": ""
      },
      "workspace_status": {
        "frozen": true,
        "frozen_by": "schematics@ibm.com",
        "frozen_at": "2021-09-28T11:34:22.306Z",
        "locked": false
      },
      "template_repo": {
        "url": "https://github.com/ptaube/tf_cloudless_sleepy",
        "commit_id": "c0a1dbc6e7afe4dad06de617a7fc35e22ddd4f95",
        "full_url": "https://github.com/ptaube/tf_cloudless_sleepy",
        "has_uploadedgitrepotar": false
      },
      "template_data": [
        {
          "id": "6fef745e-dfaa-42",
          "folder": ".",
          "compact": false,
          "type": "terraform_v0.12",
          "values_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/template_data/6fef745e-dfaa-42/values",
          "values": "",
          "values_metadata": [
            {
              "default": "hello",
              "description": "A sample_var to pass to the template.",
              "name": "sample_var",
              "type": "string"
            },
            {
              "default": "0",
              "description": "How long our local-exec will take a nap.",
              "name": "sleepy_time",
              "type": "string"
            }
          ],
          "variablestore": [
            {
              "name": "sample_var",
              "secure": false,
              "value": "THIS IS IBM CLOUD TERRAFORM CLI DEMO",
              "type": "",
              "description": "Description of sample_var"
            },
            {
              "name": "sleepy_time",
              "secure": false,
              "value": "15",
              "type": "",
              "description": ""
            }
          ],
          "has_githubtoken": false
        }
      ],
      "runtime_data": [
        {
          "id": "6fef745e-dfaa-42",
          "engine_name": "terraform",
          "engine_version": "v0.12.31",
          "state_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/runtime_data/6fef745e-dfaa-42/state_store",
          "log_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/runtime_data/6fef745e-dfaa-42/log_store"
        }
      ],
      "shared_data": {
        "resource_group_id": ""
      },
      "updated_at": "1901-01-01T00:00:00.000Z",
      "last_health_check_at": "1901-01-01T00:00:00.000Z",
      "cart_id": ""
    }

Update workspace

Use this API to update or replace the entire workspace, including the Terraform template (template_repo) or IBM Cloud catalog software template (catalog_ref) that your workspace points to.

Tip:- If you want to update workspace metadata, use the PATCH /v1/workspaces/{id} API. To update workspace variables, use the PUT /v1/workspaces/{id}/template_data/{template_id}/values API.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

PUT /v1/workspaces/{w_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.update

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • The personal access token to authenticate with your private GitHub or GitLab repository and access your Terraform template.

Path Parameters

  • The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

Replace the Workspace definition.

  • curl --request PUT --url https://schematics.cloud.ibm.com/v1/workspaces/{id} -H  Authorization: <iam_token>" -d '{"name":"testWorkspaceApi","type":[   "terraform_v0.12"],"description":"terraform workspace updated", "tags":["department:HR","application:compensation","environment:staging"], "template_repo":{"url":"https://github.com/ptaube/tf_cloudless_sleepy"}, "workspace_status":{"frozen":true},"template_data":[{"folder":".", "type":"terraform_v0.12","variablestore":[{"name":"sample_var","secure":false,"value":"THIS IS IBM CLOUD TERRAFORM CLI DEMO", "description":"Description of sample_var"},{"name":"sleepy_time","value":"15"}]}]}'
  • templateRepoRequestUpdateModel := &schematicsv1.TemplateRepoUpdateRequest{
        URL: core.StringPtr("<source_repo_url>"),
        RepoURL: core.StringPtr("<catalog_repo_url>"),
    }
    
    replaceWorkspaceOptions := &schematicsv1.ReplaceWorkspaceOptions{
        WID:          ws.ID,
        TemplateRepo: templateRepoRequestUpdateModel,
        CatalogRef: &schematicsv1.CatalogRef{
            ItemID:          core.StringPtr("<item_id>"),
            ItemName:        core.StringPtr("<item_name>"),
            ItemURL:         core.StringPtr("<item_url>"),
            ItemReadmeURL:   core.StringPtr("<item_readme_url>"),
            ItemIconURL:     core.StringPtr("<item_icon_url>"),
            OfferingVersion: core.StringPtr("<offering_version>"),
            LaunchURL:       core.StringPtr("<launch_url>"),
        },
    }
    
    replaceResponse, detailedResponse, err := schematicsService.ReplaceWorkspace(replaceWorkspaceOptions)
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(replaceResponse, "", "  ")
    fmt.Println(string(w))
  • const catalogRefModel = {
      item_icon_url: '<item_icon_url>',
      item_id: '<item_id>',
      item_name: '<item_name>',
      item_readme_url: '<item_readme_url>',
      item_url: '<item_url>',
      launch_url: '<launch_url>',
      offering_version: '<offering_version>',
    };
    
    const templateRepoUpdateRequestModel = {
      repo_url: '<catalog_repo_url>',
      url: '<source_repo_url>',
    };
    
    const params = {
      wId: '<workspace_id>',
      templateRepo: templateRepoUpdateRequestModel,
      catalogRef: catalogRefModel
    };
    
    schematicsService.replaceWorkspace(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • catalog_ref_model = {}
    catalog_ref_model['item_icon_url'] = '<item_icon_url>'
    catalog_ref_model['item_id'] = '<item_id>'
    catalog_ref_model['item_name'] = '<item_name>'
    catalog_ref_model['item_readme_url'] = '<item_readme_url>'
    catalog_ref_model['item_url'] = '<item_url>'
    catalog_ref_model['launch_url'] = '<launch_url>'
    catalog_ref_model['offering_version'] = '<offering_version>'
    
    workspace_variable_request_model = {}
    workspace_variable_request_model['name'] = 'variable_name1'
    workspace_variable_request_model['value'] = 'variable_value1'
    
    template_source_data_request_model = {}
    template_source_data_request_model['variablestore'] = [workspace_variable_request_model]
    
    template_repo_request_model = {}
    template_repo_request_model['url'] = '<source_repo_url>'
    
    workspace_response = schematics_service.replace_workspace(
        w_id='<workspace_id>',
        description="<description>", 
        name="<workspace_name>",
        catalog_ref=catalog_ref_model,
        template_data=[template_source_data_request_model],
        template_repo=template_repo_request_model,
        type=['terraform_v0.12.20'],
        location="<location>",
        resource_group="<resource_group>",
        tags=['<tags>'],
    ).get_result()
    
    print(json.dumps(workspace_response, indent = 2))
  • // Construct an instance of the CatalogRef model
    CatalogRef catalogRefModel = new CatalogRef.Builder()
    .itemIconUrl("<item_icon_url>")
    .itemId("<item_id>")
    .itemName("<item_name>")
    .itemReadmeUrl("<item_readme_url>")
    .itemUrl("<item_url>")
    .launchUrl("<launch_url>")
    .offeringVersion("<offering_version>")
    .build();
    
    // Construct an instance of the TemplateRepoUpdateRequest model
    TemplateRepoUpdateRequest templateRepoUpdateRequestModel = new TemplateRepoUpdateRequest.Builder()
    .repoUrl("<catalog_repo_url>")
    .url("<source_repo_url>")
    .build();
    
    ReplaceWorkspaceOptions replaceWorkspaceOptions = new ReplaceWorkspaceOptions.Builder()
    .wId("<workspace_id>")
    .catalogRef(catalogRefModel)
    .templateRepo(templateRepoUpdateRequestModel)
    .build();
    
    Response<WorkspaceResponse> response = service.replaceWorkspace(replaceWorkspaceOptions).execute();
    WorkspaceResponse workspaceResponse = response.getResult();

Response

Workspace details

Status Code

  • Successfully updated the workspace metadata.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • Not found. The specified workspace could not be found. Verify that the workspace ID is correct. To list workspaces in your IBM Cloud account, use the GET /v1/workspaces API.

  • The workspace is frozen and disabled. Unfreeze the workspace first before you retry the request. Or the Schematics create, update, delete action has not completed. Wait until the create, update, delete, plan, apply, destroy or refresh action completes before you try again.

  • Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

  • IBM Cloud Schematics could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "id": "us-east.workspace.testWorkspaceApi.bb026f5e",
      "name": "testWorkspaceApi",
      "crn": "crn:v1:staging:public:schematics:us-south:a/0c0c0c0c0c0c0c0c0c0c0c0c0c0c0c0:00000000-0000-0000-0000-00000000000:workspace:us-east.workspace.testWorkspaceApi.bb026f5e",
      "type": [
        "terraform_v0.12"
      ],
      "description": "terraform workspace updated",
      "resource_group": "",
      "location": "us-east",
      "tags": [
        "department:HR",
        "application:compensation",
        "environment:staging"
      ],
      "created_at": "2021-09-28T11:34:22.881Z",
      "created_by": "schematics@ibm.com",
      "status": "DRAFT",
      "failure_reason": "",
      "workspace_status_msg": {
        "status_code": "200",
        "status_msg": ""
      },
      "workspace_status": {
        "frozen": true,
        "frozen_by": "schematics@ibm.com",
        "frozen_at": "2021-09-28T14:36:08.588Z",
        "locked": false
      },
      "template_repo": {
        "url": "https://github.com/ptaube/tf_cloudless_sleepy",
        "commit_id": "c0a1dbc6e7afe4dad06de617a7fc35e22ddd4f95",
        "full_url": "https://github.com/ptaube/tf_cloudless_sleepy",
        "has_uploadedgitrepotar": false
      },
      "template_data": [
        {
          "id": "6fef745e-dfaa-42",
          "folder": ".",
          "compact": false,
          "type": "terraform_v0.12",
          "values_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/template_data/6fef745e-dfaa-42/values",
          "values": "",
          "values_metadata": [
            {
              "default": "hello",
              "description": "A sample_var to pass to the template.",
              "name": "sample_var",
              "type": "string"
            },
            {
              "default": "0",
              "description": "How long our local-exec will take a nap.",
              "name": "sleepy_time",
              "type": "string"
            }
          ],
          "variablestore": [
            {
              "name": "sample_var",
              "secure": false,
              "value": "THIS IS IBM CLOUD TERRAFORM CLI DEMO",
              "type": "",
              "description": "Description of sample_var"
            },
            {
              "name": "sleepy_time",
              "secure": false,
              "value": "15",
              "type": "",
              "description": ""
            }
          ],
          "has_githubtoken": false
        }
      ],
      "runtime_data": [
        {
          "id": "6fef745e-dfaa-42",
          "engine_name": "terraform",
          "engine_version": "v0.12.31",
          "state_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/runtime_data/6fef745e-dfaa-42/state_store",
          "log_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/us-east.workspace.testWorkspaceApi.bb026f5e/runtime_data/6fef745e-dfaa-42/log_store"
        }
      ],
      "shared_data": {
        "resource_group_id": ""
      },
      "updated_by": "schematics@ibm.com",
      "updated_at": "2021-09-28T14:36:08.595Z",
      "last_health_check_at": "1901-01-01T00:00:00.000Z",
      "cart_id": ""
    }

Delete a workspace

Deletes a workspace from IBM Cloud Schematics. Deleting a workspace does not automatically remove the IBM Cloud resources that the workspace manages. To remove all resources that are associated with the workspace, use the DELETE /v1/workspaces/{id}?destroy_resources=true API.

Note: If you delete a workspace without deleting the resources, you must manage your resources with the resource dashboard or CLI afterwards. You cannot use IBM Cloud Schematics anymore to manage your resources.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

DELETE /v1/workspaces/{w_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.delete

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • The IAM refresh token for the user or service identity. The IAM refresh token is required only if you want to destroy the Terraform resources before deleting the Schematics workspace. If you want to delete the workspace only and keep all your Terraform resources, refresh token is not required.

    Retrieving refresh token:

    • Use export IBMCLOUD_API_KEY=<ibmcloud_api_key>, and execute curl -X POST "https://iam.cloud.ibm.com/identity/token" -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=$IBMCLOUD_API_KEY" -u bx:bx.
    • For more information, about creating IAM access token and API Docs, refer, IAM access token and Create API key.

    Limitation:

    • If the token is expired, you can use refresh token to get a new IAM access token.
    • The refresh_token parameter cannot be used to retrieve a new IAM access token.
    • When the IAM access token is about to expire, use the API key to create a new access token.

Path Parameters

  • The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

Query Parameters

  • If set to true, refresh_token header configuration is required to delete all the Terraform resources, and the Schematics workspace. If set to false, you can remove only the workspace. Your Terraform resources are still available and must be managed with the resource dashboard or CLI.

  • curl -X DELETE https://schematics.cloud.ibm.com/v1/workspaces/{id} -H "Authorization: <iam_token>"
  • _, detailedResponse, err := schematicsService.DeleteWorkspace(&schematicsv1.DeleteWorkspaceOptions{
        WID:          <workspace_id>,
        RefreshToken: core.StringPtr("<refresh_token>"),
    })
    
    if err != nil {
        panic(err)
    }
    
  • const params = {
      wId: '<workspace_id>',
      refreshToken: "Refresh Token"
    };
    
    schematicsService.deleteWorkspace(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
    
  • workspace_delete_response = schematics_service.delete_workspace(
        w_id='<workspace_id>'
    ).get_result()
    
    print(json.dumps(workspace_delete_response, indent=2))
  • DeleteWorkspaceOptions deleteWorkspaceOptions = new DeleteWorkspaceOptions.Builder()
    .wId("<workspace_id>")
    .build();
    
    Response<String> response = service.deleteWorkspace(deleteWorkspaceOptions).execute();
    String workspaceDeleteResponse = response.getResult();
    
    System.out.println(workspaceDeleteResponse);

Response

Response for workspace delete job

Status Code

  • Successfully deleted the workspace.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • Deletion failed. Could not delete the workspace template information. The workspace is frozen and disabled for updates. Unfreeze the workspace first, before you try again. Or the Schematics create, update, delete action has not completed. Wait until the create, update, delete, plan, apply, destroy or refresh action completes before you try again.

  • Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

  • IBM Cloud Schematics could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Update workspace metadata

Use this API to update the following workspace metadata:

  • Workspace name (name) - Note: Updating the workspace name does not update the ID of the workspace.
  • Workspace description (description)
  • Tags (tags[])
  • Resource group (resource_group)
  • Workspace status (workspace_status.frozen)

Tip: If you want to update information about the Terraform template or IBM Cloud catalog software template that your workspace points to, use the PUT /v1/workspaces/{id} API. To update workspace variables, use the PUT /v1/workspaces/{id}/template_data/{template_id}/values API.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

PATCH /v1/workspaces/{w_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.update

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

Input parameters to update workspace metadata.

  • curl --request PATCH --url https://schematics.cloud.ibm.com/v1/workspaces/{id} -H "Authorization: <iam_token>" -d '{"name":"<workspace_name>","description": "<workspace_description>","tags": ["<tag1>", "<tag2>"], "resource_group": "<resource_grou>", "workspace_status": {"frozen": <true_or_false>}}'
  • updateWorkspaceOptions := &schematicsv1.UpdateWorkspaceOptions{
        WID: <workspace_id>,
        Description:   core.StringPtr("<description>"),
        Name:          core.StringPtr("<workspace_name>"),
        ResourceGroup: core.StringPtr("<resource_group>"),
        Tags:          []string{"<tag1>", "<tag2>"},
        WorkspaceStatus: &schematicsv1.WorkspaceStatusUpdateRequest {
            Frozen: core.BoolPtr(<true_or_false>),
        },
    }
    
    workspaceUpdateResponse, detailedResponse, err := schematicsService.UpdateWorkspace(updateWorkspaceOptions)
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(workspaceUpdateResponse, "", "  ")
    fmt.Println(string(w))
  • const workspaceStatusUpdateRequestModel = {
      frozen : '<true or false>'
    }
    
    const params = {
      wId: '<workspace_id>',
      description: '<description>',
      name: '<workspace_name>',
      type: ['terraform_v0.12.20'],
      resourceGroup: '<resource_group>',
      tags: ['<tags>'],
      workspaceStatus: workspaceStatusUpdateRequestModel
    };
    
    schematicsService.updateWorkspace(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • workspace_status_update_request_model = {}
    workspace_status_update_request_model['frozen'] = <True or False>
    
    workspace_response = schematics_service.update_workspace(
        w_id='<workspace_id>',
        description="<description>", 
        name="<workspace_name>",
        resource_group="<resource_group>",
        tags=['<tag1>', '<tag2>'],
        workspace_status=workspace_status_update_request_model
    ).get_result()
    
    print(json.dumps(workspace_response, indent=2))
  • WorkspaceStatusUpdateRequest workspaceStatusUpdateRequestModel = new WorkspaceStatusUpdateRequest.Builder()
    .frozen(<true_or_false>)
    .build();
    
    UpdateWorkspaceOptions updateWorkspaceOptions = new UpdateWorkspaceOptions.Builder()
    .wId("testString")
    .description("<description>")
    .name("<workspace_name>")
    .tags(new java.util.ArrayList<String>(java.util.Arrays.asList("<tag>")))
    .workspaceStatus(workspaceStatusUpdateRequestModel)
    .build();
    
    Response<WorkspaceResponse> response = service.updateWorkspace(updateWorkspaceOptions).execute();
    WorkspaceResponse workspaceResponse = response.getResult();
    
    System.out.println(workspaceResponse);

Response

Workspace details

Status Code

  • Successfully updated the workspace metadata.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • Not found. The specified workspace could not be found. Verify that the workspace ID is correct. To list workspaces in your IBM Cloud account, use the GET /v1/workspaces API.

  • Patch failed. The workspace is marked as frozen. Unfreeze the workspace before you retry the request.

  • Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

  • IBM Cloud Schematics could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "id": "myworkspace-123456",
      "name": "myworkspace",
      "type": [
        "terraform_v0.12"
      ],
      "description": "This is a workspace created with the API",
      "resource_group": "a1b23aa11bb22cc55",
      "location": "eu-de",
      "tags": [],
      "created_at": "2019-11-06T16:19:32.352Z",
      "created_by": "user@us.ibm.com",
      "status": "INACTIVE",
      "workspace_status_msg": {
        "status_code": "",
        "status_msg": ""
      },
      "workspace_status": {
        "frozen": false,
        "locked": false
      },
      "template_repo": {
        "url": "https://github.com/myorg/myrepo"
      },
      "template_data": [
        {
          "id": "d1369548-1bc2-4d",
          "folder": ".",
          "type": "terraform_v0.12",
          "values_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/template_data/a123456b/values\n            values: ''\n            values_metadata:\n              - name: variable1\n                type: value1\n              - name: variable2\n                type: value2\n            variablestore:\n              - name: variable1\n                secure: false\n                value: value1\n                type: ''\n                description: ''\n              - name: variable2\n                secure: false\n                value: value2\n                type: ''\n                description: ''\n        runtime_data:\n          - id: a123456b\n            engine_name: terraform\n            engine_version: v0.12.24\n            state_store_url: >-\n              https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a123456b/state_store\n            log_store_url: >-\n              https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a123456b/log_store\n        shared_data:\n          resource_group_id: ''\n        updated_at: '0001-01-01T00:00:00Z'\n        last_health_check_at: '0001-01-01T00:00:00Z'     "
        }
      ]
    }

Show workspace template readme

Retrieve the README.md file of the Terraform of IBM Cloud catalog template that your workspace points to.

GET /v1/workspaces/{w_id}/templates/readme

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

Query Parameters

  • The GitHub or GitLab branch where the README.md file is stored, or the commit ID or tag that references the README.md file that you want to retrieve. If you do not specify this option, the README.md file is retrieved from the master branch by default.

  • The format of the readme file. Value ''markdown'' will give markdown, otherwise html

    Allowable values: [markdown,html]

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/templates/readme -H "Authorization: <iam_token>"
  • readme, detailedResponse, err := schematicsService.GetWorkspaceReadme(&schematicsv1.GetWorkspaceReadmeOptions{
        WID: <workspace_id>,
    })
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(readme, "", "  ")
    fmt.Println(string(w))
  • const params = {
      wId: '<workspace_id>',
    };
    
    schematicsService.getWorkspaceReadme(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • template_readme = schematics_service.get_workspace_readme(
        w_id='<workspace_id>'
    ).get_result()
    
    print(json.dumps(template_readme, indent=2))
  • GetWorkspaceReadmeOptions getWorkspaceReadmeOptions = new GetWorkspaceReadmeOptions.Builder()
    .wId("<workspace_id>")
    .build();
    
    Response<TemplateReadme> response = service.getWorkspaceReadme(getWorkspaceReadmeOptions).execute();
    TemplateReadme templateReadme = response.getResult();
    
    System.out.println(templateReadme);

Response

The README.md file for the template used by the workspace

Status Code

  • Successfully retrieved the README.md of the template that your workspace points to.

  • The source URL format is invalid, the source repository is not supported by Schematics, or the source repository API returns an HTTP error.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • The README.md file could not be retrieved, because an HTTP error was returned by Git.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "readme": "&lt;p&gt;This is my readme.&lt;/p&gt;  \n"
    }

Upload a TAR file to your workspace

Provide your Terraform template by uploading a TAR file from your local machine. Before you use this API, you must create a workspace without a link to a GitHub or GitLab repository with the POST /v1/workspaces API.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

PUT /v1/workspaces/{w_id}/template_data/{t_id}/template_repo_upload

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.update

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • The ID of the workspace where you want to upload your .tar file. To find the workspace ID, use the GET /v1/workspaces API.

  • The ID of the Terraform template in your workspace. When you create a workspace, a unique ID is assigned to your Terraform template, even if no template was provided during workspace creation. To find this ID, use the GET /v1/workspaces API and review the template_data.id value.

Form Parameters

  • Template tar file

  • curl -X PUT https://schematics.cloud.ibm.com/v1/workspaces/{id}/template_data/{template_id}/template_repo_upload -H "Authorization: <iam_token>" -H "Content-Type: multipart/form-data" --form "file =@<file_path>/mytarfile.tar"
  • fileReader, _ := os.Open(<path_of_tar_file>)
    fileReaderWrapper := ioutil.NopCloser(fileReader)
    
    uploadTarOptions := &schematicsv1.UploadTemplateTarOptions{
        WID:             <workspace_id>,
        TID:             <template_id>,
        File:            fileReaderWrapper,
        FileContentType: core.StringPtr("multipart/form-data"),
    }
    
    uploadResult, httpResponse, err := schematicsService.UploadTemplateTar(uploadTarOptions)
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(uploadResult, "", "  ")
    fmt.Println(string(w))
  • fileStream = fs.createReadStream('<path_of_tar_file>');
    
    schematicsService.uploadTemplateTar({
        wId : '<workspace_id>',
        tId: '<template_id>',
        fileContentType: "multipart/form-data",
        file: fileStream
    })
    .then(res => {
      console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
      console.warn(err);
    })
  • file = open("<path_of_tar_file>", "rb")
    
    template_repo_tar_upload_response = schematics_service.upload_template_tar(
        w_id='<workspace_id>',
        t_id='<template_id>',
        file = file,
        file_content_type = 'multipart/form-data'
    ).get_result()
    
    print(json.dumps(template_repo_tar_upload_response, indent=2))
  • UploadTemplateTarOptions uploadTemplateTarOptions = new UploadTemplateTarOptions.Builder()
    .wId("<workspace_id>")
    .tId("<template_id>")
    .file(new File("<path_of_tar_file>"))
    .fileContentType("multipart/form-data")
    .build();
    
    Response<TemplateRepoTarUploadResponse> response = service.uploadTemplateTar(uploadTemplateTarOptions).execute();
    TemplateRepoTarUploadResponse templateRepoTarUploadResponse = response.getResult();
    
    System.out.println(templateRepoTarUploadResponse);

Response

TemplateRepoTarUploadResponse -

Status Code

  • Successfully uploaded the TAR file to your workspace.

  • The tar file could not be read. Make sure that the tar file was created in the right format and try again.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • Not found. The specified workspace could not be found. Verify that the workspace ID is correct. To list workspaces in your IBM Cloud account, use the GET /v1/workspaces API.

  • Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

List workspace input variables

Retrieve a list of input variables that are declared in your Terraform or IBM Cloud catalog template.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v1/workspaces/{w_id}/template_data/{t_id}/values

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.template_values

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

  • The ID of the Terraform template in your workspace. When you create a workspace, the Terraform template that your workspace points to is assigned a unique ID. Use the GET /v1/workspaces to look up the workspace IDs and template IDs or template_data.id in your IBM Cloud account.

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/template_data/{template_id}/values -H "Authorization: <iam_token>"      
  • inputValues, detailedResponse, err := schematicsService.GetWorkspaceInputs(&schematicsv1.GetWorkspaceInputsOptions{
        WID: <workspace_id>,
        TID: <template_id>,
    })
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(inputValues, "", "  ")
    fmt.Println(string(w))
  • const params = {
      wId: '<workspace_id>',
      tId: '<template_id>',
    };
    
    schematicsService.getWorkspaceInputs(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • template_values = schematics_service.get_workspace_inputs(
        w_id='<workspace_id>',
        t_id='<template_id>'
    ).get_result()
    
    print(json.dumps(template_values, indent=2))
  • GetWorkspaceInputsOptions getWorkspaceInputsOptions = new GetWorkspaceInputsOptions.Builder()
    .wId("<workspace_id>")
    .tId("<template_id>")
    .build();
    
    Response<TemplateValues> response = service.getWorkspaceInputs(getWorkspaceInputsOptions).execute();
    TemplateValues templateValues = response.getResult();
    System.out.println(templateValues);

Response

Information about the input variables that are declared in the template that your workspace points to.

Status Code

  • Successfully retrieved a list of input variables that are declared in your template.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "values_metadata": [
        {
          "name": "variable_name",
          "type": "string"
        }
      ],
      "variablestore": [
        {
          "name": "variable_name",
          "secure": false,
          "value": "variable_value",
          "type": "",
          "description": ""
        }
      ]
    }

Replace workspace input variables

Replace or Update the input variables for the template that your workspace points to.

PUT /v1/workspaces/{w_id}/template_data/{t_id}/values

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.template_values

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

  • The ID of the Terraform template in your workspace. When you create a workspace, the Terraform template that your workspace points to is assigned a unique ID. Use the GET /v1/workspaces to look up the workspace IDs and template IDs or template_data.id in your IBM Cloud account.

Replace a Workspace input values

  • curl --location -g --request PUT https://schematics.cloud.ibm.com/v1/workspaces/{id}/template_data/{template_id}/values --header "Authorization: <iam_token>" --header "Content-Type: application/json" --data-raw "{"env_values": [{"name": "env_variable_name", "value": "env_variable_value" }], "values": "string", "variablestore": [{"description": "<variable_description>", "name": "<variable_name>", "secure": <true_or_false>, "use_default": <true_or_false>, "type": "<variable_datatype>", "value": "<variable_value>"}]}

Response

UserValues -

Status Code

  • Successfully updated input variables for the template that your workspace points to.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Get workspace template details

Retrieve detailed information about the Terraform template that your workspace points to.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v1/workspaces/{w_id}/templates/values

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.template_metadata_values

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • The ID of the workspace for which you want to retrieve input parameters and values. To find the workspace ID, use the GET /workspaces API.

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/templates/values -H "Authorization: <iam_token>"

Response

Response with the template details in your workspace

Status Code

  • Successfully retrieved details about the Terraform template that your workspace points to.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "template_data": [
        {
          "id": "1111aa2221-a11a-11",
          "folder": ".",
          "type": "terraform_v0.12",
          "values_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/template_data/71111aa2221-a11a-11/values",
          "values": "",
          "values_metadata": [
            {
              "name": "variable_name1",
              "type": "string"
            },
            {
              "name": "variable_name2",
              "type": "string"
            }
          ],
          "variablestore": [
            {
              "name": "variable_name1",
              "secure": false,
              "value": "variable_value1",
              "type": "",
              "description": ""
            },
            {
              "name": "variable_name2",
              "secure": false,
              "value": "variable_value2",
              "type": "",
              "description": ""
            }
          ]
        }
      ],
      "runtime_data": [
        {
          "id": "1111aa2221-a11a-11",
          "engine_name": "terraform",
          "engine_version": "v0.12.24",
          "state_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/1111aa2221-a11a-11/state_store",
          "log_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/1111aa2221-a11a-11/log_store"
        }
      ],
      "shared_data": {
        "region": "",
        "resource_group_id": ""
      }
    }

List workspace variable metadata

Retrieve the metadata for all the workspace input variables that are declared in the template that your workspace points to.

GET /v1/workspaces/{w_id}/template_data/{t_id}/values_metadata

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • The ID of the workspace for which you want to retrieve the metadata of the input variables that are declared in the template. To find the workspace ID, use the GET /v1/workspaces API.

  • The ID of the Terraform template for which you want to retrieve the metadata of your input variables. When you create a workspace, the Terraform template that your workspace points to is assigned a unique ID. To find this ID, use the GET /v1/workspaces API and review the template_data.id value.

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/template_data/{template_id}/values_metadata -H "Authorization: <iam_token>"

Response

A list of input variables and its metadata for the workspace template.

Status Code

  • Successfully retrieved the metadata of the input variables for the template that your workspace points to.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "name": "variable_name",
      "type": "string"
    }

List workspace output values

Retrieve a list of Terraform output variables. You define output values in your Terraform template to include information that you want to make accessible for other Terraform templates.

GET /v1/workspaces/{w_id}/output_values

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • The ID of the workspace for which you want to retrieve output parameters and values. To find the workspace ID, use the GET /workspaces API.

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/output_values -H "Authorization: <iam_token>"

Response

Terraform output values that are defined in the Terraform template or IBM Cloud software template.

Status Code

  • Successfully retrieved the output values in JSON format.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "id": "cef7da5d-dd7c-48",
      "folder": ".",
      "type": "terraform_v0.12",
      "output_values": [
        {
          "sshcommand": {
            "sensitive": false,
            "type": "string",
            "value": "ssh root@111.22.111.111"
          }
        }
      ]
    }

List workspace resources

Retrieve a list of IBM Cloud resources that you created with your workspace.

GET /v1/workspaces/{w_id}/resources

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

  • curl --location --request GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/resources -H "Authorization: Bearer <access_token>" -H "refresh_token: <refresh_token>"--header "Content-Type: application/json" --data-raw '{"name": "testbranchReso","type": ["terraform_v0.12"],"description": "terraform workspace","tags": ["test:bbbranch"],"template_repo": {"url": "<source_repo_url>"},"template_data": [{"folder": ".","type": "terraform_v0.12","variablestore": [{"value": "variable_value1","name": "ibmcloud_api_key","type": "string","secure": true}],"env_values":[{"TF_LOG":"debug"}]}]}'
  • resourcesList, detailedResponse, err := schematicsService.GetWorkspaceResources(&schematicsv1.GetWorkspaceResourcesOptions{
        WID: <workspace_id>,
    })
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(resourcesList, "", "  ")
    fmt.Println(string(w))
  • const params = {
      wId: '<workspace_id>',
    };
    
    schematicsService.getWorkspaceResources(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • list_template_resources = schematics_service.get_workspace_resources(
        w_id='<workspace_id>'
    ).get_result()
    
    print(json.dumps(list_template_resources, indent=2))
  • GetWorkspaceResourcesOptions getWorkspaceResourcesOptions = new GetWorkspaceResourcesOptions.Builder()
    .wId("<workspace_id>")
    .build();
    
    Response<List<TemplateResources>> response = service.getWorkspaceResources(getWorkspaceResourcesOptions).execute();
    List<TemplateResources> listTemplateResources = response.getResult();
    
    System.out.println(listTemplateResources);

Response

Information about the resources provisioned by the workspace template.

Status Code

  • Successfully retrieved the resources in JSON format.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "id": "examples-99f04c50-71aa-40",
      "folder": "examples/ibm-vsi",
      "type": "terraform_v0.12",
      "resources": [
        {
          "resource_id": "120765732",
          "resource_name": "vm1",
          "resource_type": "ibm_compute_vm_instance",
          "resource_crn": "",
          "resource_icon_url": "",
          "resource_controller_url": "https://cloud.ibm.com/gen1/infrastructure/virtual-server/120765732/details#main",
          "resource_group_name": "",
          "resource_status": "Active",
          "resource_tainted": false,
          "resource_extension": {
            "resource_name": "vm1",
            "resource_data_array": [
              {
                "property_key": "dedicated_acct_host_only",
                "property_value": false
              },
              {
                "property_key": "disks",
                "property_value": [
                  25
                ]
              },
              {
                "property_key": "file_storage_ids",
                "property_value": []
              },
              {
                "property_key": "ipv6_enabled",
                "property_value": false
              },
              {
                "property_key": "ipv6_static_enabled",
                "property_value": false
              },
              {
                "property_key": "private_network_only",
                "property_value": true
              },
              {
                "property_key": "quote_id"
              },
              {
                "property_key": "wait_time_minutes",
                "property_value": 90
              },
              {
                "property_key": "dedicated_host_id"
              },
              {
                "property_key": "private_interface_id",
                "property_value": 85535164
              },
              {
                "property_key": "public_bandwidth_limited"
              },
              {
                "property_key": "public_bandwidth_unlimited",
                "property_value": false
              },
              {
                "property_key": "tags"
              },
              {
                "property_key": "block_storage_ids",
                "property_value": []
              },
              {
                "property_key": "ip_address_id_private",
                "property_value": 173990966
              },
              {
                "property_key": "resource_name",
                "property_value": "vm1"
              },
              {
                "property_key": "resource_status",
                "property_value": "Active"
              },
              {
                "property_key": "bulk_vms",
                "property_value": []
              },
              {
                "property_key": "evault"
              },
              {
                "property_key": "flavor_key_name"
              },
              {
                "property_key": "ipv4_address_private",
                "property_value": "10.142.123.187"
              },
              {
                "property_key": "network_speed",
                "property_value": 100
              },
              {
                "property_key": "placement_group_id"
              },
              {
                "property_key": "ssh_key_ids"
              },
              {
                "property_key": "cores",
                "property_value": 1
              },
              {
                "property_key": "secondary_ip_addresses",
                "property_value": []
              },
              {
                "property_key": "resource_controller_url",
                "property_value": "https://cloud.ibm.com/gen1/infrastructure/virtual-server/120765732/details#main"
              },
              {
                "property_key": "ipv4_address",
                "property_value": ""
              },
              {
                "property_key": "hourly_billing",
                "property_value": true
              },
              {
                "property_key": "ipv6_address_id"
              },
              {
                "property_key": "notes",
                "property_value": ""
              },
              {
                "property_key": "timeouts"
              },
              {
                "property_key": "dedicated_host_name"
              },
              {
                "property_key": "local_disk",
                "property_value": false
              },
              {
                "property_key": "public_security_group_ids",
                "property_value": []
              },
              {
                "property_key": "ip_address_id"
              },
              {
                "property_key": "public_subnet_id"
              },
              {
                "property_key": "datacenter",
                "property_value": "dal09"
              },
              {
                "property_key": "id",
                "property_value": "120765732"
              },
              {
                "property_key": "public_ipv6_subnet"
              },
              {
                "property_key": "user_metadata"
              },
              {
                "property_key": "domain",
                "property_value": "example.com"
              },
              {
                "property_key": "private_subnet_id",
                "property_value": 876563
              },
              {
                "property_key": "private_vlan_id",
                "property_value": 3096262
              },
              {
                "property_key": "public_interface_id",
                "property_value": 85535166
              },
              {
                "property_key": "ipv6_address"
              },
              {
                "property_key": "private_security_group_ids",
                "property_value": []
              },
              {
                "property_key": "public_ipv6_subnet_id"
              },
              {
                "property_key": "os_reference_code",
                "property_value": "CENTOS_7_64"
              },
              {
                "property_key": "secondary_ip_count"
              },
              {
                "property_key": "image_id"
              },
              {
                "property_key": "memory",
                "property_value": 1024
              },
              {
                "property_key": "placement_group_name"
              },
              {
                "property_key": "private_subnet",
                "property_value": "10.142.123.128/26"
              },
              {
                "property_key": "transient",
                "property_value": false
              },
              {
                "property_key": "hostname",
                "property_value": "vm1"
              },
              {
                "property_key": "post_install_script_uri"
              },
              {
                "property_key": "public_subnet"
              },
              {
                "property_key": "public_vlan_id"
              },
              {
                "property_key": "datacenter_choice"
              }
            ],
            "resource_type": "ibm_compute_vm_instance"
          }
        }
      ],
      "resources_count": 1
    }

Get Terraform statefile URL

Retrieve the URL to the Terraform statefile (terraform.tfstate). You use the URL to access the Terraform statefile. The Terraform statefile includes detailed information about the IBM Cloud resources that you provisioned with IBM Cloud Schematics and Schematics uses the file to determine future create, modify, or delete actions for your resources. To show the content of the Terraform statefile, use the GET /v1/workspaces/{id}/runtime_data/{template_id}/state_store API.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v1/workspaces/{w_id}/state_stores

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.template_state_stores

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • The ID of the workspace for which you want to retrieve the Terraform statefile. To find the workspace ID, use the GET /v1/workspaces API.

  • curl -X GET  https://schematics.cloud.ibm.com/v1/workspaces/{workspace id}/state_stores/{activity id} -H  "Authorization: <iam_token>" Cache-Control: no-cache                      
  • curl -X GET <state_store_url> -H "Authorization: <iam_token>"
  • stateFile, detailedResponse, err := schematicsService.GetWorkspaceState(&schematicsv1.GetWorkspaceStateOptions{
        WID: <workspace_id>,
    })
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(stateFile, "", "  ")
    fmt.Println(string(w))
  • const params = {
      wId: '<workspace_id>',
    };
    
    schematicsService.getWorkspaceState(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • state_store_response_list = schematics_service.get_workspace_state(
        w_id='<workspace_id>'
    ).get_result()
    
    print(json.dumps(state_store_response_list, indent=2))
  • GetWorkspaceStateOptions getWorkspaceStateOptions = new GetWorkspaceStateOptions.Builder()
    .wId("<workspace_id>")
    .build();
    
    Response<StateStoreResponseList> response = service.getWorkspaceState(getWorkspaceStateOptions).execute();
    StateStoreResponseList stateStoreResponseList = response.getResult();
    
    System.out.println(stateStoreResponseList);

Response

Information about the Terraform statefile URL.

Status Code

  • Successfully retrieved the URL to the Terraform statefile.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "version": 3,
      "terraform_version": "0.11.15",
      "serial": 1,
      "lineage": "8afcf3e5-a635-39ba-8b7a-930fc52d91c4",
      "modules": [
        {
          "path": [
            "root"
          ],
          "outputs": {
            "rendered_template": {
              "sensitive": false,
              "type": "string",
              "value": "Hello, I am a template. My sample_var value = THIS IS IBM CLOUD TERRAFORM CLI DEMO"
            }
          },
          "resources": {
            "data.template_file.test": {
              "type": "template_file",
              "depends_on": [],
              "primary": {
                "id": "a66b4e292bc3632041929666cc093a78bf8842030b165e38eca429d5561c51b2",
                "attributes": {
                  "id": "a66b4e292bc3632041929666cc093a78bf8842030b165e38eca429d5561c51b2",
                  "rendered": "Hello, I am a template. My sample_var value = THIS IS IBM CLOUD TERRAFORM CLI DEMO",
                  "template": "Hello, I am a template. My sample_var value = ${sample_var}",
                  "vars.%": "1",
                  "vars.sample_var": "THIS IS IBM CLOUD TERRAFORM CLI DEMO"
                },
                "meta": {},
                "tainted": false
              },
              "deposed": [],
              "provider": "provider.template"
            },
            "null_resource.sleep": {
              "type": "null_resource",
              "depends_on": [],
              "primary": {
                "id": "6705893306070343458",
                "attributes": {
                  "id": "6705893306070343458",
                  "triggers.%": "1",
                  "triggers.uuid": "eacbeee0-6710-f57c-76a1-5a1785d589d4"
                },
                "meta": {},
                "tainted": false
              },
              "deposed": [],
              "provider": "provider.null"
            }
          },
          "depends_on": []
        }
      ]
    }

Show Terraform statefile content

Show the content of the Terraform statefile (terraform.tfstate) that was created when your Terraform template was applied in IBM Cloud. The statefile holds detailed information about the IBM Cloud resources that were created by IBM Cloud Schematics and Schematics uses the file to determine future create, modify, or delete actions for your resources.

GET /v1/workspaces/{w_id}/runtime_data/{t_id}/state_store

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • The ID of the workspace for which you want to retrieve the Terraform statefile. To find the workspace ID, use the GET /v1/workspaces API.

  • The ID of the Terraform template for which you want to retrieve the Terraform statefile. When you create a workspace, the Terraform template that your workspace points to is assigned a unique ID. To find this ID, use the GET /v1/workspaces API and review the template_data.id value.

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/runtime_data/{template_id}/state_store -H "Authorization: <iam_token>"
  • statefile, detailedResponse, err := schematicsService.GetWorkspaceTemplateState(&schematicsv1.GetWorkspaceTemplateStateOptions{
        WID: <workspace_id>,
        TID: <template_id>,
    })
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(statefile, "", "  ")
    fmt.Println(string(w))
  • const params = {
      wId: '<workspace_id>',
      tId: '<template_id>',
    };
    
    schematicsService.getWorkspaceTemplateState(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • template_state_store = schematics_service.get_workspace_template_state(
        w_id='<workspace_id>',
        t_id='<template_id>'
    ).get_result()
    
    print(json.dumps(template_state_store, indent=2))
  • GetWorkspaceTemplateStateOptions getWorkspaceTemplateStateOptions = new GetWorkspaceTemplateStateOptions.Builder()
    .wId("<workspace_id>")
    .tId("<template_id>")
    .build();
    
    Response<TemplateStateStore> response = service.getWorkspaceTemplateState(getWorkspaceTemplateStateOptions).execute();
    TemplateStateStore templateStateStore = response.getResult();
    
    System.out.println(templateStateStore);

Response

The content of the Terraform statefile (terraform.tfstate).

Status Code

  • Successfully retrieved the information from the Terraform statefile.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "version": 3,
      "terraform_version": "0.11.14",
      "serial": 1,
      "lineage": "98aba884-11c1-7e45-f9d6-f895bbf80654",
      "modules": [
        {
          "path": [
            "root"
          ],
          "outputs": {},
          "resources": {
            "data.ibm_is_image.ubuntu": {
              "type": "ibm_is_image",
              "depends_on": [],
              "primary": {
                "id": "abc111-1111-1111-aaaa-123456789",
                "attributes": {
                  "architecture": "amd64",
                  "crn": "crn:v1:bluemix:public:is:us-south:::image:abc111-1111-1111-aaaa-123456789",
                  "id": "abc111-1111-1111-aaaa-123456789",
                  "name": "ubuntu-18.04-amd64",
                  "os": "ubuntu-18-04-amd64",
                  "status": "available",
                  "visibility": "public"
                },
                "meta": {},
                "tainted": false
              },
              "deposed": [],
              "provider": "provider.ibm"
            },
            "data.ibm_is_ssh_key.ssh_key_id": {
              "type": "ibm_is_ssh_key",
              "depends_on": [],
              "primary": {
                "id": "111111-0000-0001-0000-0000001111a1",
                "attributes": {
                  "fingerprint": "SHA256:A1B3aaaabbb3A/ABCDEaaAA",
                  "id": "111111-0000-0001-0000-0000001111a1",
                  "length": "2048",
                  "name": "mykey",
                  "type": "rsa"
                },
                "meta": {},
                "tainted": false
              },
              "deposed": [],
              "provider": "provider.ibm"
            }
          },
          "depends_on": []
        }
      ]
    }

Get workspace job log URL

Get the Terraform log file URL for a workspace job. You can retrieve the log URL for jobs that were created with the PUT /v1/workspaces/{id}/apply, POST /v1/workspaces/{id}/plan, or DELETE /v1/workspaces/{id}/destroy API.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v1/workspaces/{w_id}/actions/{activity_id}/logs

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.log_stores

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • The ID of the workspace for which you want to retrieve the Terraform statefile. To find the workspace ID, use the GET /v1/workspaces API.

  • The ID of the activity or job, for which you want to retrieve details. To find the job ID, use the GET /v1/workspaces/{id}/actions API.

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/actions/{action_id}/logs -H "Authorization: <iam_token>"
  • curl -X GET <log_url> -H "Authorization: <access_token>"
  • activityLogResult, detailedResponse, err := schematicsService.GetWorkspaceActivityLogs(&schematicsv1.GetWorkspaceActivityLogsOptions{
        WID:        <workspace_id>,
        ActivityID: <activity_id>,
    })
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(activityLogResult, "", "  ")
    fmt.Println(string(w))
  • const params = {
      wId: '<workspace_id>',
      activityId: '<activity_id>',
    };
    
    schematicsService.getWorkspaceActivityLogs(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • workspace_activity_logs = schematics_service.get_workspace_activity_logs(
        w_id='<workspace_id>',
        activity_id='<activity_id>'
    ).get_result()
    
    print(json.dumps(workspace_activity_logs, indent=2))
  • GetWorkspaceActivityLogsOptions getWorkspaceActivityLogsOptions = new GetWorkspaceActivityLogsOptions.Builder()
    .wId("<workspace_id>")
    .activityId("<activity_id>")
    .build();
    
    Response<WorkspaceActivityLogs> response = service.getWorkspaceActivityLogs(getWorkspaceActivityLogsOptions).execute();
    WorkspaceActivityLogs workspaceActivityLogs = response.getResult();
    
    System.out.println(workspaceActivityLogs);

Response

Workspace job logs for all the templates in the workspace

Status Code

  • Successfully retrieved the log file URL for your job.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • The specified workspace or action could not be found. Verify that you entered the correct workspace and action ID. To find the ID of your workspace, use the GET /v1/workspaces API. To find the ID of the action, use the GET /v1/workspaces/{id}/actions API.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses

Get latest workspace job log URL for all workspace templates

Retrieve the log file URL for the latest job of a template that ran against your workspace. You use this URL to retrieve detailed logs for the latest job.

GET /v1/workspaces/{w_id}/log_stores

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/log_stores -H "Authorization: <iam_token>"
  • curl -X GET <log_store_url> -H "Authorization: <iam_token>"
  • activityLogResult, detailedResponse, err := schematicsService.GetWorkspaceLogUrls(&schematicsv1.GetWorkspaceLogUrlsOptions{
        WID: <workspace_id>,
    })
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(activityLogResult, "", "  ")
    fmt.Println(string(w))
  • const params = {
      wId: '<workspace_id>',
    };
    
    schematicsService.getWorkspaceLogUrls(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • log_store_response_list = schematics_service.get_workspace_log_urls(
        w_id='<workspace_id>'
    ).get_result()
    
    print(json.dumps(log_store_response_list, indent=2))
  • GetWorkspaceLogUrlsOptions getWorkspaceLogUrlsOptions = new GetWorkspaceLogUrlsOptions.Builder()
    .wId("<workspace_id>")
    .build();
    
    Response<LogStoreResponseList> response = service.getWorkspaceLogUrls(getWorkspaceLogUrlsOptions).execute();
    LogStoreResponseList logStoreResponseList = response.getResult();
    
    System.out.println(logStoreResponseList);

Response

List of log file URL that ran against your workspace.

Status Code

  • Successfully retrieved the log URL for the most recent job that ran against your workspace.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses

Show logs for the latest action for a workspace template

Show the Terraform logs for the most recent job of a template that ran against your workspace.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v1/workspaces/{w_id}/runtime_data/{t_id}/log_store

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.state_stores

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

  • The ID of the Terraform template or IBM Cloud catalog software template in the workspace. Use the GET /v1/workspaces to look up the workspace IDs and template IDs or template_data.id

Query Parameters

  • Enter false to replace the first line in each Terraform command section, such as Terraform INIT or Terraform PLAN, with Schematics INIT (Schematics PLAN) in your log output. In addition, the log lines Starting command: terraform init -input=false -no-color and Starting command: terraform apply -state=terraform.tfstate -var-file=schematics.tfvars -auto-approve -no-color are suppressed. All subsequent command lines still use the Terraform command prefix. To remove this prefix, use the log_tf_prefix option.

  • false will hide all the terraform command prefix in the log statements

  • false will hide all the null resource prefix in the log statements

  • true will format all logs to withhold the original format of ansible output in the log statements

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/runtime_data/{template_id}/log_store -H "Authorization: <iam_token>"
  • templateLogResult, detailedResponse, err := schematicsService.GetTemplateLogs(&schematicsv1.GetTemplateLogsOptions{
        WID: <workspace_id>,
        TID: <template_id>,
    })
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(templateLogResult, "", "  ")
    fmt.Println(string(w))
  • const params = {
      wId: '<workspace_id>',
      tId: '<template_id>',
    };
    
    schematicsService.getTemplateLogs(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • template_log_store_string = schematics_service.get_template_logs(
        w_id='<workspace_id>',
        t_id='<template_id>'
    ).get_result()
    
    print(json.dumps(template_log_store_string, indent=2))
  • GetTemplateLogsOptions getTemplateLogsOptions = new GetTemplateLogsOptions.Builder()
    .wId("<workspace_id>")
    .tId("<template_id>")
    .build();
    
    Response<String> response = service.getTemplateLogs(getTemplateLogsOptions).execute();
    String templateLogStoreString = response.getResult();
    
    System.out.println(templateLogStoreString);

Response

The Terraform logs for the most recent workspace job.

Status Code

  • Successfully retrieved the Terraform logs for the most recent workspace job.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • The specified workspace or template could not be found. Verify that you entered the correct workspace and template ID. To find the workspace and template ID, use the GET /v1/workspaces API.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Show logs for a workspace job

Show the Terraform logs for an job that ran against your workspace.

GET /v1/workspaces/{w_id}/runtime_data/{t_id}/log_store/actions/{activity_id}

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • The ID of the workspace. To find the workspace ID, use the GET /v1/workspaces API.

  • The ID of the Terraform template or IBM Cloud catalog software template in the workspace. Use the GET /v1/workspaces to look up the workspace IDs and template IDs or template_data.id

  • The ID of the activity or job, for which you want to retrieve details. To find the job ID, use the GET /v1/workspaces/{id}/actions API.

Query Parameters

  • Enter false to replace the first line in each Terraform command section, such as Terraform INIT or Terraform PLAN, with Schematics INIT (Schematics PLAN) in your log output. In addition, the log lines Starting command: terraform init -input=false -no-color and Starting command: terraform apply -state=terraform.tfstate -var-file=schematics.tfvars -auto-approve -no-color are suppressed. All subsequent command lines still use the Terraform command prefix. To remove this prefix, use the log_tf_prefix option.

  • false will hide all the terraform command prefix in the log statements

  • false will hide all the null resource prefix in the log statements

  • true will format all logs to withhold the original format of ansible output in the log statements

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces/{id}/runtime_data/{template_id}/log_store/actions/{action_id} -H "Authorization: <iam_token>"
  • activityLogResult, detailedResponse, err := schematicsService.GetTemplateActivityLog(&schematicsv1.GetTemplateActivityLogOptions{
        WID:        <workspace_id>,
        TID:        <template_id>,
        ActivityID: <activity_id>,
    })
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(activityLogResult, "", "  ")
    fmt.Println(string(w))
  • const params = {
      wId: '<workspace_id>',
      activityId: '<activity_id>',
      tId: '<template_id>',
    };
    
    schematicsService.getTemplateActivityLog(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • workspace_activity_template_log_string = schematics_service.get_template_activity_log(
        w_id='<workspace_id>',
        activity_id='<activity_id>',
        t_id='<template_id>'
    ).get_result()
    
    print(json.dumps(workspace_activity_template_log_string, indent=2))
  • GetTemplateActivityLogOptions getTemplateActivityLogOptions = new GetTemplateActivityLogOptions.Builder()
    .wId("<workspace_id>")
    .activityId("<activity_id>")
    .tId("<template_id>")
    .build();
    
    Response<String> response = service.getTemplateActivityLog(getTemplateActivityLogOptions).execute();
    String workspaceActivityTemplateLogString = response.getResult();
    
    System.out.println(workspaceActivityTemplateLogString);

Response

Workspace template job log as a string

Status Code

  • Successfully retrieved the template activity logs as text (string).

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • The specified workspace, action, or template could not be found. Verify that you entered the correct workspace, action ID, and template ID. To find the ID of your workspace or template, use the GET /v1/workspaces API. To find the ID of the action, use the GET /v1/workspaces/{id}/actions API.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

List actions

Retrieve a list of all Schematics actions that depends on the API endpoint that you have access. For example, if you use an API endpoint for a geography, such as North America, only actions that are created in us-south or us-east are retrieved.

For more information, about supported API endpoints, see API endpoints.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v2/actions

Auditing

Calling this method generates the following auditing event.

  • schematics.action.list

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Query Parameters

  • The starting position of the item in the list of items. For example, if you have three workspaces in your account, the first workspace is assigned position number 0, the second workspace is assigned position number 1, and so forth. If you have 6 workspaces and you want to list the details for workspaces 2-6, enter 1. To limit the number of workspaces that is returned, use the limit option in addition to the offset option. Negative numbers are not supported and are ignored.

    Possible values: value ≥ 0

  • The maximum number of items that you want to list. The number must be a positive integer between 1 and 2000. If no value is provided, 100 is used by default.

    Possible values: 1 ≤ value ≤ 2000

    Default: 100

  • Name of the field to sort-by; Use the '.' character to delineate sub-resources and sub-fields (eg. owner.last_name). Prepend the field with '+' or '-', indicating 'ascending' or 'descending' (default is ascending) Ignore unrecognized or unsupported sort field

  • Level of details returned by the get method

    Allowable values: [ids,summary]

  • curl --location --request GET https://schematics.cloud.ibm.com/v2/actions/actions --header "Authorization:  <access_token>"
  • listActionsOptions := schematicsService.NewListActionsOptions()
    
    actionList, response, err := schematicsService.ListActions(listActionsOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(actionList, "", "  ")
    fmt.Println(string(b))
    
  • action_list = schematics_service.list_actions().get_result()
    print (json.dumps(action_list, indent=2))
  • schematicsService.listActions({})
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
  • ListActionsOptions listActionsOptions = new ListActionsOptions.Builder()
    .build();
    Response<ActionList> response = service.listActions(listActionsOptions).execute();
    ActionList actionList = response.getResult();
    System.out.println(actionList);

Response

List of Action definition response

Status Code

  • Successfully retrieved all actions.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "total_count": "xx total number of records",
      "limit": "xx records returned",
      "offset": "0 record skipped",
      "actions": [
        {
          "name": "Your action name",
          "description": "The description of the action",
          "id": "Your action ID",
          "location": "user location",
          "resource_group": "user resource group",
          "namespace": "target namespace name",
          "tags": [
            "string"
          ],
          "user_state": {
            "state": "live",
            "set_by": "user@in.ibm.com",
            "set_at": "2021-03-03T13:11:14.553Z"
          },
          "state": {
            "status_code": "normal",
            "status_message": "Action is ready for execution."
          },
          "sys_lock": {
            "sys_locked_at": "1901-01-01T00:00:00.000Z"
          },
          "created_at": "2021-03-03T13:11:14.558Z",
          "created_by": "user@in.ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        }
      ]
    }

Create an action

Create an IBM Cloud Schematics action to run on a single target or groups of target hosts, roles, policies, or steps to deploy your resources in the target hosts. You can run the IBM Cloud resources the order in which you want to execute them. Note If your Git repository already contains a host file. Schematics does not overwrite the host file already present in your Git repository. For sample templates, see IBM Cloud Automation templates.

The Schematics action API now supports bastion host connection with non-root user, and bastion connection type is marked as optional, when inventory connection type is set as Windows Remote Management(winrm).

For more information, about the Schematics create action, see ibmcloud schematics action create. Note you cannot update the location and region once an action is created. Also, make sure your IP addresses are in the allowlist.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

POST /v2/actions

Auditing

Calling this method generates the following auditing event.

  • schematics.action.create

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • The personal access token to authenticate with your private GitHub or GitLab repository and access your Terraform template.

Create Action request

  • curl --location --request POST https://schematics.cloud.ibm.com/v2/actions --header "Authorization: <access_token> " --header "Content-Type: application/json" --data-raw "{"name": "Example-12ab2",   "description": "action_description", "location": "location string", "resource_group": "resource_group", "source": {"source_type": "git", "git": {"git_repo_url": "https://github.com/Cloud-Schematics/ansible-is-instance-actions"}}}
  • action_list = schematics_service.create_action(
    name="mskpythonsamples-templates",
    description="<short description>",
    location="<location>",
    resource_group="<resource_group>",
    tags=["User environment,mytest"]
    source={
    ‘git’:
    {
    ‘git_repo_url’:“https://github.com/Cloud-Schematics/cli-demo”
    }
    }
    ).get_result()
    print (json.dumps(action_list, indent=2))
  • CreateActionOptions createActionOptions = new CreateActionOptions.Builder()
    .name("msksampletest-checkCreate")
     .build();
    
    Response<Action> response = service.createAction(createActionOptions).execute();
    Action actionList = response.getResult();
    
    System.out.println(actionList);
  • const params = {
    name:"Users action name",
    description:"short description",
    location:"us",
    resource_group:"Users resource group",
    tags:["env:prod", "mytest"],
    source:{
    "git":
    {
    'git_repo_url':"https://github.com/Cloud-Schematics/repo_name"
    }
    }
    
    };
    
    schematicsService.createAction(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
  • createActionOptions := schematicsService.NewCreateActionOptions()
    createActionOptions.SetName("set your name")
    createActionOptions.SetDescription("short description")
    tags := []string{"env:prod", "mytest1"}
    createActionOptions.Tags = tags
    createActionOptions.SetLocation("set your location")
    createActionOptions.SetResourceGroup("set the resource group")
    source := schematicsv1.ExternalSource{
    SourceType: core.StringPtr("git"),
    Git: &schematicsv1.ExternalSourceGit{
    GitRepoURL: core.StringPtr("set your Git repository URL"),
    },
    }
    createActionOptions.SetSource(&source)
    actionList, response, err := schematicsService.CreateAction(createActionOptions)
    if err != nil {
    panic(err)
    }

Response

Complete Action details with user inputs and system generated data

Status Code

  • Successfully created a new Action definition

  • Bad request - Verify that the information in your request body is complete and correctly formatted in JSON.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • The specified resource already exists

  • Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "offset": 0,
      "limit": 1,
      "count": 6,
      "actions": [
        {
          "name": "Users action name",
          "description": "The description of the action",
          "location": "Users location",
          "resource_group": "Users resource group",
          "tags": [
            "string"
          ],
          "user_state": {
            "state": "live",
            "set_by": "user@.ibm.com",
            "set_at": "021-03-12T09:45:44.568286818Z"
          },
          "source": {
            "source_type": "git",
            "git": {
              "git_repo_url": "https://github.com/Cloud-Schematics/repo_name"
            },
            "catalog": {},
            "external_scm": {},
            "cos_bucket": {}
          },
          "source_type": "GitHub",
          "command_parameter": "user playbook name with the extension",
          "bastion": {
            "name": "bastionhost",
            "type": "string",
            "description": "string",
            "resource_query": "53.46.14.52",
            "credential_ref": "ssh_key",
            "created_at": "1901-01-01T00:00:00.000Z",
            "updated_at": "1901-01-01T00:00:00.000Z",
            "sys_lock": {
              "sys_locked_at": "1901-01-01T00:00:00.000Z"
            }
          },
          "targets_ini": "[webserverhost] \n 132.00.00.0",
          "credentials": [
            {
              "name": "ssh_key",
              "value": "*******",
              "metadata": {
                "type": "string",
                "secure": true
              }
            }
          ],
          "inputs": [
            {
              "name": "upassword",
              "value": "*******",
              "metadata": {
                "type": "string",
                "default_value": "user@123abc",
                "secure": true
              }
            },
            {
              "name": "dbname",
              "value": "dbfoo",
              "metadata": {
                "type": "string",
                "default_value": "foodb"
              }
            },
            {
              "name": "dbuser",
              "value": "xxx",
              "metadata": {
                "type": "string",
                "default_value": "xxx"
              }
            },
            {
              "name": "mysql_port",
              "value": "xxxx",
              "metadata": {
                "type": "string",
                "default_value": "xxxx"
              }
            },
            {
              "name": "httpd_port",
              "value": "xx",
              "metadata": {
                "type": "string",
                "default_value": "xx"
              }
            }
          ],
          "id": "Users action ID",
          "crn": "crn:v1::lalalalalallalallala::",
          "account": "0dlalalalalla",
          "source_created_at": "1901-01-01T00:00:00.000Z",
          "source_updated_at": "1901-01-01T00:00:00.000Z",
          "created_at": "2021-02-08T12:29:55.214Z",
          "created_by": "user@.ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z",
          "namespace": "Default",
          "state": {
            "status_code": "pending",
            "status_message": "Create Action is in queue, Please wait till action complete"
          },
          "sys_lock": {
            "sys_locked_at": "1901-01-01T00:00:00.000Z"
          }
        }
      ]
    }

Get action details

Retrieve the detailed information of an actions from your IBM Cloud account. This API returns a URL to the log file that you can retrieve by using the GET /v2/actions/{action_id}/logs API.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

GET /v2/actions/{action_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.action.read

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

Path Parameters

  • Action Id. Use GET /actions API to look up the Action Ids in your IBM Cloud account.

Query Parameters

  • Level of details returned by the get method

    Allowable values: [summary,detailed]

  • curl --location --request GET https://schematics.cloud.ibm.com/v2/actions/{action_id} --header "Authorization:  <access_token> "
  • GetActionOptions getActionOptions = new GetActionOptions.Builder()
    .actionId("set your action ID.")
    .build();
    Response<Action> response = service.getAction(getActionOptions).execute();
    Action action = response.getResult();
    
    System.out.println(action);
  • action = schematics_service.get_action(action_id="Users action ID").get_result()
    print (json.dumps(action, indent=2))
  • const params = {
    actionId: "Users action ID",
    };
    
    schematicsService.getAction(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
  • getActionOptions := schematicsService.NewGetActionOptions("testString",)
    getActionOptions.SetActionID("set your action ID")
    
    action, response, err := schematicsService.GetAction(getActionOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(action, "", "  ")
    fmt.Println(string(b))

Response

Complete Action details with user inputs and system generated data

Status Code

  • Successfully got the Action definition

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • Not found. The specified action could not be found. Verify that the action ID is correct. To list actions in your IBM Cloud account, use the GET /v2/actions API.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "name": "Users action name",
      "description": "The description of the action",
      "id": "Users action ID",
      "location": "Users location",
      "tags": [
        "environment details, for example env:test",
        "mytest"
      ],
      "user_state": {
        "state": "live",
        "set_by": "user@in.ibm.com",
        "set_at": "2021-03-12T09:45:44.568Z"
      },
      "state": {
        "status_code": "normal",
        "status_message": "Action is ready for execution."
      },
      "sys_lock": {
        "sys_locked_at": "1901-01-01T00:00:00.000Z"
      },
      "created_at": "2021-03-12T09:45:44.571Z",
      "created_by": "user@in.ibm.com",
      "updated_at": "1901-01-01T00:00:00.000Z"
    }

Delete an action

Delete a Schematics action and specify the Ansible playbook that you want to run against your IBM Cloud resources. Note you cannot delete or stop the job activity from an ongoing execution of an action defined in the playbook. You can repeat the execution of same job, whenever you patch the actions. For more information, about the Schematics action state, see Schematics action state diagram.

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

DELETE /v2/actions/{action_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.action.delete

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • Equivalent to -force options in the command line

  • Auto propagate the chaange or deletion to the dependent resources

Path Parameters

  • Action Id. Use GET /actions API to look up the Action Ids in your IBM Cloud account.

  • curl --location --request DELETE https://schematics.cloud.ibm.com/v2/actions/{action_id} --header "Authorization:  <access_token> "
  • deleteActionOptions := schematicsService.NewDeleteActionOptions("set your deletion action options",)
    deleteActionOptions.SetActionID("set your Action ID")
    
    response, err := schematicsService.DeleteAction(deleteActionOptions)
    if err != nil {
    panic(err)
    }
  • response = schematics_service.delete_action(
    action_id="Set your action ID"
    ).get_result()
    
    print(json.dumps(response, indent=2))
  • const params = {
    actionId: "Users action ID",
    };
    
    schematicsService.deleteAction(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
  • DeleteActionOptions deleteActionOptions = new DeleteActionOptions.Builder()
    .actionId("Users action ID")
    .build();
    
    service.deleteAction(deleteActionOptions).execute();

Response

Status Code

  • Successfully initiated stopping of the job, and deleted the job record

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • Not found. The specified action could not be found. Verify that the action ID is correct. To list actions in your IBM Cloud account, use the GET /v2/actions API.

  • Failed to delete the specific resoure. If the resource is locked, try again after unlocking.

  • Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

  • IBM Cloud Schematics could not process the request, due to a temporary overloading or maintenance. Try to reduce your request rate, or retry after a few minutes. If the error persists, contact IBM Cloud support.

No Sample Response

This method does not specify any sample responses.

Update an action

Update or replace an action to change the action state from the critical state to normal state, or pending state to the normal state for a successful execution. For more information, about the Schematics action state, see Schematics action state diagram.

The Schematics action API now supports bastion host connection with non-root user, and bastion connection type is marked as optional, when inventory connection type is set as Windows Remote Management(winrm).

Note you cannot update the location and region once an action is created. Also, make sure your IP addresses are in the [allowlist](https://cloud.ibm.com/docs/schematics?topic=schematics-allowed-ipaddresses].

Authorization

Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see Schematics service access roles and required permissions.

PATCH /v2/actions/{action_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.action.update

Request

Custom Headers

  • The IAM access token for your IBM Cloud account. You can use the client ID and the secret that are used by the IBM Cloud command line 'bx / bx'. To retrieve the token, run ic iam oauth-tokens in the IBM Cloud command line.

  • The personal access token to authenticate with your private GitHub or GitLab repository and access your Terraform template.

Path Parameters

  • Action Id. Use GET /actions API to look up the Action Ids in your IBM Cloud account.

Action

  • curl --location --request PATCH https://schematics.cloud.ibm.com/v2/actions/{action_id} --header "Authorization: <access_token>" --header "Content-Type: application/json" --data-raw "{"name": "<action_name>", "description": "<action_description>", "location": "<action_location>", "resource_group": "<resource_group>", "source": {"source_type": "git", "git": {"git_repo_url": "https://github.com/Cloud-Schematics/lamp-simple"}}, "command_parameter": "<YAML_or_YML file>", "tags": ["string"], "credentials": [{ "name": "ssh_key", "value": "<ssh_key>" 
    ,"metadata": { "string"}}], "bastion": {"name": "bastionhost", "type": "string", "description": "string", "resource_query": "<IP_address", "credential_ref": "ssh_key" }, "inputs": [{ "name": "string", "value": "string", "metadata": {"type": "string", "secure": <true_or_false>, "default_value": "string" }}, {"name": "string", "value": "string", "metadata": { "type": "string", "default_value": "string" }}, { "name": "dbuser", "value": "string", "metadata": {  "type": "string", "default_value": "string" }}, { "name": "mysql_port", "value": "string", "metadata": { "type": "string", "default_value": "string" }}, { "name": "httpd_port", "value": "string", "metadata": { "type": "string", "secure": <false_or_true>, "default_value": "string" } }], "source_type": "GitHub",   "targets_ini": "[hostgroupname] 
     "IP address" 
     host2 
     [hostgroupname] 
     "IP address" "}
  • updateActionOptions := schematicsService.NewUpdateActionOptions("teststring",)
    updateActionOptions.SetActionID("us.ACTION.sundeepKumar-patchpart.44875f1b")
    updateActionOptions.SetName("set your name")
    updateActionOptions.SetDescription("short description")
    tags := []string{"env:prod", "mytest1"}
    updateActionOptions.Tags = tags
    updateActionOptions.SetLocation("set your location")
    updateActionOptions.SetResourceGroup("set your resource group name")
    source := schematicsv1.ExternalSource{
    SourceType: core.StringPtr("git"),
    Git: &schematicsv1.ExternalSourceGit{
    GitRepoURL: core.StringPtr("set your Git repository URL"),
    },
    }
    updateActionOptions.SetSource(&source)
    actionList, response, err := schematicsService.UpdateAction(updateActionOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(actionList, "", "v2/actions")
    fmt.Println(string(b))
  • action = schematics_service.update_action(
    action_id="Users action ID").get_result()
    print (json.dumps(action, indent=2))
  • const params = {
    actionId: "Users action ID",
    xGithubToken: "Users Github token",
    description:"Updated short description"
    };
    
    schematicsService.updateAction(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
  • UpdateActionOptions updateActionOptions = new UpdateActionOptions.Builder()
    .actionId("action ID")
    .xGithubToken("testString")
    .build();
    
    Response<Action> response = service.updateAction(updateActionOptions).execute();
    Action action = response.getResult();
    
    System.out.println(action);

Response

Complete Action details with user inputs and system generated data

Status Code

  • Successfully updated an action.

  • The IAM authorization token for the request is missing, invalid, expired, or has no account. Check that the token value is correct or generate a new token with the ibmcloud iam oauth-tokens command.

  • Unauthorized access. Check that you have the correct access credentials and permissions.

  • Not found. The specified action could not be found. Verify that the action ID is correct. To list actions in your IBM Cloud account, use the GET /v2/actions API.

  • Too many requests have been made within a time window. "IBM Cloud Schematics supports 50 API requests per minute, per host, and per customer. The host can be us-east, us-south, eu-gb, or eu-de region". Wait before calling the API again.

  • Internal server error. IBM Cloud Schematics is currently unavailable. Wait a few minutes, then try again. If the error persists, contact IBM Cloud support.

Example responses
  • {
      "name": "Users action name",
      "description": "Updated short description",
      "location": "us",
      "tags": [
        "env:prod",
        "mytest"
      ],
      "user_state": {
        "state": "live",
        "set_by": "user@in.ibm.com",
        "set_at"