IBM Cloud API Docs

Introduction

IBM Cloud Schematics delivers Terraform 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, multitier 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 following list provides the detailed documentation.

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/ibm-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 that is constructed by SDK's authenticator factory during client initialization. It avoids hardcoding 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 by 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 by using environment variables with the same name in the environment where the applications ran.

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/ibm-schematics/schematics/v1');

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 that is configured by constructing an authenticator instance provides the configuration attributes programmatically and then passing this instance to a client instantiation.

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/ibm-schematics/schematics/v1');
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 needed 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 needed 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, the 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 region. Make sure that your data can be stored in these regions before you start by using Schematics.

The GetServiceURLForRegion function with the x-ibm-region parameters in the API returns the service URL to be used for the specified region. Following table lists the servers object in the API definition.

API endpoint
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
IBM Cloud Schematics actions that are 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
IBM Cloud Schematics actions that are 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.

Error handling code
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 needed 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 might 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 are made within a time window. Wait and then call the API again.
500 Internal Server Error IBM Cloud Schematics is disabled. Your request might not be processed. Wait 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 might 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

If an error response from the server endpoint the Java SDK throws 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. The list provides predefined exceptions and their corresponding statusCode and message content.

Exception handling
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:

Java exception fields
Field Description
statusCode HTTP response status code
message the error message returned in the response
debuggingInfo a Map<String, Object> that contains the unmarshalled error response object when a JSON error response is returned.
It provides 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

If an error response from the server endpoint the Node SDK creates an Error object that contains either the HTTP response error message or a generic error message. If the network problems the axios package generates an Error object. This Error object is passed as the first parameter to the callback function, its failure describes the content as shown in the following table.

Node exception fields
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

If an error response from the server endpoint the Python SDK throws an ApiException that includes more information about the cause of the failure. It provides the following details:

Python exception fields
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

If an error response from the server endpoint the Go SDK creates an error object that contains either the HTTP response error message or a generic error message.

An extra detailedResponse is returned by the service that contains the following fields:

Go exception fields
Field Description
StatusCode HTTP response status code
Result JSON error response object that is 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

  • Level of details returned by the get method

    Allowable values: [ids,summary]

  • The resource group (by default, fetch from all resource groups) name or ID

  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces -H "Authorization: <iam_token>"    
  • curl -X GET https://schematics.cloud.ibm.com/v1/workspaces?profile=summary -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_v1.0"
          ],
          "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_v1.0",
              "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_v1.0"],"location": "<location>","description": "<workspace_description>","resource_group": "<resource_group_ID>","tags": [],"template_repo": {"url": "<source_repo_url>"},"template_data": [{"folder": ".","type": "terraform_v1.0","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_v1.0"],"location": "<location>","description": "<workspace_description>","resource_group": "<resource_group_ID>","tags": [],"template_repo": {"url": ""},"template_data": [{"folder": ".","type": "terraform_v1.0","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":"<workspace_name>","type": ["terraform_v1.0"],"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_v1.0","variablestore":[ {"name":"sample_var","secure":false,"value":"THIS IS IBM CLOUD TERRAFORM CLI DEMO", "description":"Description of sample_var"},{   "name":"sleepy_time","value":"15"}]}]}'
  • curl --request POST --url https://schematics.cloud.ibm.com/v1/workspaces -H 'authorization: Bearer <access_token>' \ 'cache-control: no-cache' \ 'content-type: application/json' \ 'postman-token: dc2ea316-12a3-597b-4353-3150078d5d5e' \ '{"name": "<workspace_name>","shared_data": {"region": "us-south"}, "type": ["terraform_v1.0"], "description": "terraform workspace", "template_repo": {"url": "https://github.com/msundeep4/test-template-private-module"}, "template_data": [ {"folder": ".","type": "terraform_v1.0", "env_values": [{"__netrc__":"[['github.com','msundeep4','<githubtoken>']]"}] }]}'                
  • templateSourceDataRequestModel := &schematicsv1.TemplateSourceDataRequest{
        Folder: core.StringPtr("."),
        Type:   core.StringPtr("terraform_v1.0"),
        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_v1.0"},
        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_v1.0',
      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_v1.0'],
      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'] = 'terraform_v1.0'
    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_v1.0'],
        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_v1.0")
    .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_v1.0")))
    .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_v1.0"
      ],
      "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_v1.0",
          "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_v1.0"
      ],
      "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": "<displays your Git repository URL>",
        "commit_id": "<displays the workspace version of the Git repository templates that are used by same repository>",
        "full_url": "<displays your Git repository URL with all the files.>",
        "has_uploadedgitrepotar": false
      },
      "template_data": [
        {
          "id": "6fef745e-dfaa-42",
          "folder": ".",
          "compact": false,
          "type": "terraform_v1.0",
          "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_v1.0"],"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_v1.0","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_v1.0"
      ],
      "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_v1.0",
          "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_v1.0'],
      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_v1.0"
      ],
      "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_v1.0",
          "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

Response after uploading Template in tar file format

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": "445ec9f4-e157-41",
        "folder": ".",
        "type": "terraform_v0.12",
        "related_resources": [
          {
            "resource_id": "data.template_file.test",
            "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": "",
            "resource_tainted": false,
            "resource_extension": {
              "resource_name": "",
              "resource_type": ""
            }
          }
        ],
        "null_resources": [
          {
            "resource_id": "6776381372089043143",
            "resource_name": "null_resource.sleep",
            "resource_type": "null_resource",
            "resource_crn": "",
            "resource_icon_url": "",
            "resource_controller_url": "",
            "resource_group_name": "",
            "resource_status": "",
            "resource_tainted": false,
            "resource_extension": {
              "resource_name": "",
              "resource_type": ""
            }
          }
        ],
        "resources_count": 1
      }
    ]

Get Terraform statefile URL

This API is deprecated, and is replaced by the GET /v2/jobs/{job_id}/files, with file_type equal state_file. 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

This API is deprecated, and is replaced by the GET /v2/jobs/{job_id}/files, with file_type equal state_file. 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
  • {
      "action_id": "123456ba12345b",
      "name": "APPLY",
      "templates": [
        {
          "template_id": "a1245319-b1235",
          "template_type": "terraform_v0.12",
          "log_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a1245319-b1235/log_store/actions/7123456ba12345b"
        }
      ]
    }

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
  • {
      "runtime_data": [
        {
          "id": "a134567b24-12",
          "engine_name": "terraform",
          "engine_version": "terraformv0.12.24",
          "log_store_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a134567b24-12/log_store"
        }
      ]
    }

Show latest logs 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": "<action_location>", "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,ids]

  • 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": "2021-03-12T09:45:44.568Z"
      },
      "source": {
        "source_type": "",
        "git": {
          "git_repo_url": "https://github.com/Cloud-Schematics/repo_name"
        },
        "catalog": {},
        "external_scm": {},
        "cos_bucket": {}
      },
      "bastion": {
        "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"
        }
      },
      "id": "Users action ID",
      "crn": "crn:v1:lalalal.ACTION.actionname.97888799a",
      "account": "69999991919199191f",
      "source_created_at": "1901-01-01T00:00:00.000Z",
      "source_updated_at": "1901-01-01T00:00:00.000Z",
      "created_at": "2021-03-12T09:45:44.571Z",
      "created_by": "user@in.ibm.com",
      "updated_at": "2021-03-12T09:52:48.649Z",
      "state": {
        "status_code": "pending",
        "status_job_id": "Users job ID",
        "status_message": "Action is in queue. Wait until the action completes update."
      },
      "playbook_names": [
        "xx.yml",
        "errxx.yml"
      ],
      "sys_lock": {
        "sys_locked_at": "1901-01-01T00:00:00.000Z"
      }
    }

Upload a TAR file to an action

Update your template by uploading tape archive file (.tar) file from your local machine. Before you use this API, you must create an action without a link to a GitHub or GitLab repository with the POST /v2/actions 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 /v2/actions/{action_id}/template_repo_upload

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.

Path Parameters

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

Form Parameters

  • Template tar file

Response

Response after uploading Template in tar file format

Status Code

  • Successfully received the Git repository as input TAR file for the 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.

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

No Sample Response

This method does not specify any sample responses.

List workspace jobs

Retrieve a list of all jobs that ran against a workspace. Jobs are generated when you use the apply, plan, destroy, and refresh, command API.

GET /v1/workspaces/{w_id}/actions

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 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/{id}/actions -H "Authorization: <iam_token>"
  • listWorkspaceActivitiesOptions := &schematicsv1.ListWorkspaceActivitiesOptions{
        WID: <workspace_id>,
    }
    
    listWorkspaceActivitiesResult, detailedResponse, err := schematicsService.ListWorkspaceActivities(listWorkspaceActivitiesOptions)
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(listWorkspaceActivitiesResult, "", "  ")
    fmt.Println(string(w))
  • const params = {
      wId: '<workspace_id>',
    };
    
    schematicsService.listWorkspaceActivities(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • workspace_activities = schematics_service.list_workspace_activities(
        w_id='<workspace_id>'
    ).get_result()
    
    print(json.dumps(workspace_activities, indent=2))
  • ListWorkspaceActivitiesOptions listWorkspaceActivitiesOptions = new ListWorkspaceActivitiesOptions.Builder()
    .wId("<workspace_id>")
    .build();
    
    Response<WorkspaceActivities> response = service.listWorkspaceActivities(listWorkspaceActivitiesOptions).execute();
    WorkspaceActivities workspaceActivities = response.getResult();
    
    System.out.println(workspaceActivities);

Response

List of workspace jobs

Status Code

  • Successfully retrieved list of workspace jobs.

  • 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
  • {
      "workspace_name": "myworkspace",
      "workspace_id": "myworkspace-123456",
      "actions": [
        {
          "action_id": "a11223334b11224345",
          "name": "PLAN",
          "status": "COMPLETED",
          "message": [],
          "performed_by": "user@us.ibm.com",
          "performed_at": "2019-08-21T14:07:25.814Z",
          "templates": [
            {
              "template_id": "a1234b-2124",
              "template_type": "terraform_v0.12",
              "start_time": "2019-08-21T14:07:26.120Z",
              "end_time": "2019-08-21T14:07:30.088Z",
              "status": "COMPLETED",
              "message": "{\"messagekey\":\"M2001_ActivitySuccessful\",\"parms\":{},\"requestid\":\"1234b1234b123-1234n13\",\"timestamp\":\"2019-08-21T14:07:30.088498532Z\"}",
              "log_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a1234b-2124/log_store/actions/11223334b11224345                "
            }
          ]
        }
      ]
    }

Get workspace job details

Get the details for a workspace job that ran against the workspace. This API returns the job status and a URL to the log file that you can retrieve by using the GET /v1/workspaces/{id}/actions/{action_id}/logs API.

GET /v1/workspaces/{w_id}/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 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} -H "Authorization: <iam_token>"
  • activityResponse, detailedResponse, err := schematicsService.GetWorkspaceActivity(&schematicsv1.GetWorkspaceActivityOptions{
        WID:        <workspace_id>,
        ActivityID: <activity_id>,
    })
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(activityResponse, "", "  ")
    fmt.Println(string(w))
  • const params = {
      wId: '<workspace_id>',
      activityId: '<activity_id>',
    };
    
    schematicsService.getWorkspaceActivity(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • workspace_activity = schematics_service.get_workspace_activity(
        w_id='<workspace_id>',
        activity_id='<activity_id>'
    ).get_result()
    
    print(json.dumps(workspace_activity, indent=2))
  • GetWorkspaceActivityOptions getWorkspaceActivityOptions = new GetWorkspaceActivityOptions.Builder()
    .wId("<workspace_id>")
    .activityId("<activity_id>")
    .build();
    
    Response<WorkspaceActivity> response = service.getWorkspaceActivity(getWorkspaceActivityOptions).execute();
    WorkspaceActivity workspaceActivity = response.getResult();
    
    System.out.println(workspaceActivity);

Response

Information about the workspace jobs.

Status Code

  • Successfully retrieved the workspace jobs details.

  • 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 requested workspace or job cannot be located. Check that you have the correct workspace ID and job IDs in your request.

  • 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
  • {
      "action_id": "a11223334b11224345",
      "name": "PLAN",
      "status": "COMPLETED",
      "message": [],
      "performed_by": "user@us.ibm.com",
      "performed_at": "2019-08-21T14:07:25.814Z",
      "templates": [
        {
          "template_id": "a1234b-2124",
          "template_type": "terraform_v0.12",
          "start_time": "2019-08-21T14:07:26.120Z",
          "end_time": "2019-08-21T14:07:30.088Z",
          "status": "COMPLETED",
          "message": "{\"messagekey\":\"M2001_ActivitySuccessful\",\"parms\":{},\"requestid\":\"1234b1234b123-1234n13\",\"timestamp\":\"2019-08-21T14:07:30.088498532Z\"}",
          "log_url": "https://schematics.cloud.ibm.com/v1/workspaces/myworkspace-123456/runtime_data/a1234b-2124/log_store/actions/11223334b11224345                "
        }
      ]
    }

Stop the workspace job

Stop an ongoing schematics job that runs against your workspace. Note: If you remove the Schematics apply job that runs against your workspace, any changes to your IBM Cloud resources that are already applied are not reverted. If a creation, update, or deletion is currently in progress, Schematics waits for the job to be completed first. Then, any other resource creations, updates, or deletions that are included in your Terraform template file are ignored.

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}/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 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 DELETE https://schematics.cloud.ibm.com/v1/workspaces/{id}/actions/{action_id} -H "Authorization: <iam_token>"
  • curl -X DELETE  https://schematics.cloud.ibm.com//v1/workspaces/{workspace_id}/actions/{job_id}?signal=interrupt  -H "Authorization: <iam_token>"
  • curl -X DELETE  https://schematics.cloud.ibm.com//v1/workspaces/{workspace_id}/actions/{job_id}?signal=force-stop  -H "Authorization: <iam_token>"
  • curl -X DELETE  https://schematics.cloud.ibm.com//v1/workspaces/{workspace_id}/actions/{job_id}?signal=terminate -H "Authorization: <iam_token>"
  • _, detailedResponse, err := schematicsService.DeleteWorkspaceActivity(&schematicsv1.DeleteWorkspaceActivityOptions{
        WID:        <workspace_id>,
        ActivityID: <activity_id>,
    })
    
    if err != nil {
        panic(err)
    }
  • const params = {
      wId: '<workspace_id>',
      activityId: '<activity_id>',
    };
    
    schematicsService.deleteWorkspaceActivity(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • workspace_activity_apply_result = schematics_service.delete_workspace_activity(
        w_id='<workspace_id>',
        activity_id='<activity_id>'
    ).get_result()
    
    print(json.dumps(workspace_activity_apply_result, indent=2))
  • DeleteWorkspaceActivityOptions deleteWorkspaceActivityOptions = new DeleteWorkspaceActivityOptions.Builder()
    .wId("<workspace_id>")
    .activityId("<activity_id>")
    .build();
    
    Response<WorkspaceActivityApplyResult> response = service.deleteWorkspaceActivity(deleteWorkspaceActivityOptions).execute();
    WorkspaceActivityApplyResult workspaceActivityApplyResult = response.getResult();
    
    System.out.println(workspaceActivityApplyResult);

Response

Response after successfully initiating a request to apply the Terraform template in IBM Cloud.

Status Code

  • Successfully initiated the stopping of workspace job.

  • The specified action cannot be stopped because the job completed successfully or a user in the account already requested to stop this action. Use the GET /v1/workspace/{id}/actions API to find the details 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.

  • Not found. The requested workspace or job cannot be located. Check that you have the correct workspace ID and job IDs in your request.

  • The specified resource is marked as frozen. Unfreeze the resource before you retry the request.

  • 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
  • {
      "requestid": "cf844c29-dc3e-4c34-af5e-c23d6a306c29",
      "timestamp": "2022-06-13T09:26:48.245Z",
      "messageid": "M1058",
      "message": "Cannot stop an activity that is already completed. Please check the activity details",
      "statuscode": 400
    }

Run Terraform Commands

Run Terraform state commands to modify the workspace state file, by using the IBM Cloud Schematics 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}/commands

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.

    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.

command value

  • curl --location --request PUT 'https://schematics.cloud.ibm.com/v1/workspaces/<workspace_id>/commands' --header "refresh_token: <refresh_token>' --header 'Authorization: <iam_token>' --header 'Content-Type: application/json' --data-raw '{"commands": [{"command": "state show","command_params": "data.template_file.test","command_name": "Test1","command_desc": "Showing state","command_onerror": "continue"},{"command": "taint","command_params": "null_resource.sleep","command_name": "Test2", "command_desc": "Marking taint","command_onerror": "continue"},], "operation_name": "Workspace Command","description": "Executing command"}'
  • terraformCommandModel := &schematicsv1.TerraformCommand{
    Command: core.StringPtr("<command_to_be_executed>"),
    CommandParams: core.StringPtr("<command_parameters>"),
    CommandName: core.StringPtr("<command_name>"),
    CommandDesc: core.StringPtr("<command_description>"),
    }
    
    runWorkspaceCommandsOptions := schematicsService.NewRunWorkspaceCommandsOptions(
    WID: core.StringPtr("<workspace_id>"),
    RefreshToken: core.StringPtr("<refresh_token>"),
    Commands: []schematicsv1.TerraformCommand{*terraformCommandModel},
    OperationName: core.StringPtr("<operation_name>"),
    Description: core.StringPtr("<operation_description>"),
    )
    
    workspaceActivityCommandResult, response, err := schematicsService.RunWorkspaceCommands(runWorkspaceCommandsOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(workspaceActivityCommandResult, "", ""),
    fmt.Println(string(b))
  • const terraformCommandModel = {
      command: '<command_to_be_executed>',
      command_params: '<command_parameters>',
      command_name: '<command_name>',
      command_desc: '<command_description>',
    };
    
    const params = {
      wId: '<workspace_id>,'
      refreshToken: '<refresh_token>',
      commands: [terraformCommandModel],
      operationName: '<operation_name>',
      description: '<operation_description>',
    };
    
    schematicsService.runWorkspaceCommands(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • terraform_command_model = {
      'command': '<command_to_be_executed>',
      'command_params': '<command_parameters>',
      'command_name': '<command_name>',
      'command_desc': '<command_description>',
    }
    
    workspace_activity_command_result = schematics_service.run_workspace_commands(
    w_id='<workspace_id>',
    refresh_token='<refresh_token>',
    commands=[terraform_command_model],
    operation_name='<operation_name>',
    description='<operation_description>'
    ).get_result()
    print(json.dumps(workspace_activity_command_result, indent=2)),
  • TerraformCommand terraformCommandModel = new TerraformCommand.Builder()
    .command("<command_to_be_executed>")
    .commandParams("<command_parameters>")
    .commandName("<command_name>")
    .commandDesc("<command_description>")
    .build();
    RunWorkspaceCommandsOptions runWorkspaceCommandsOptions = new RunWorkspaceCommandsOptions.Builder()
    .wId("<workspace_id>")
    .refreshToken("<refresh_token>")
    .commands(new java.util.ArrayList<TerraformCommand>(java.util.Arrays.asList(terraformCommandModel)))
    .operationName("<operation_name>")
    .description("<operation_description>")
    .build();
    Response<WorkspaceActivityCommandResult> response = service.runWorkspaceCommands(runWorkspaceCommandsOptions).execute();
    WorkspaceActivityCommandResult workspaceActivityCommandResult = response.getResult();
    System.out.println(workspaceActivityCommandResult);
    Node.JS
    const terraformCommandModel = {
    command: '<command_to_be_executed>',
    command_params: '<command_parameters>',
    command_name: '<command_name>',
    command_desc: '<command_description>',
    };
    const params = {
    wId: '<workspace_id>',
    refreshToken: '<refresh_token>',
    commands: [terraformCommandModel],
    operationName: '<operation_name>',
    description: '<operation_description>',
    };
    schematicsService.runWorkspaceCommands(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });

Response

Response after successfully initiating a request to run a workspace command on the stack of resources provisioned using Terraform.

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.

  • Workspace Command 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
  • {
      "activityid": "223423423adfadf123456"
    }

Perform a Schematics `apply` job

Run a Schematics apply job against your workspace. An apply job provisions, modifies, or removes the IBM Cloud resources that you described in the Terraform template that your workspace points to. Depending on the type and number of resources that you want to provision or modify, this process might take a few minutes, or even up to hours to complete. During this time, you cannot make changes to your workspace. After all updates are applied, the state of the files is persisted to determine what resources exist in your IBM Cloud account.

Important: Your workspace must be in an Inactive, Active, Failed, or Stopped state to perform a Schematics apply job. After all updates are applied, the state of the files is persisted to determine what resources exist in your IBM Cloud account.

Note: This API returns an activity or job ID that you use to retrieve the log URL with the GET /v1/workspaces/{id}/actions/{action_id}/logs API.

Important: Applying a template might incur costs. Make sure to review the pricing information for the resources that you specified in your templates before you apply the template in IBM Cloud. To find a summary of job that Schematics is about to perform, create a Terraform execution plan with the POST /v1/workspaces/{id}/plan 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}/apply

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace-resources.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 IAM refresh token for the user or service identity.

    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.
  • The IAM delegated token for your IBM Cloud account. This token is required for requests that are sent via the UI only.

Path Parameters

  • The ID of the workspace for which you want to run a Schematics apply job. To find the workspace ID, use the GET /workspaces API.

Workspace 'apply' job options

  • curl -X PUT https://schematics.cloud.ibm.com/v1/workspaces/{id}/apply -H "Authorization: Bearer <iam_token>" -H "refresh_token: <refresh_token>"
  • curl -X GET <log_url> -H "Authorization: Bearer <iam_token>"
  • applyWorkspaceCommandOptions := &schematicsv1.ApplyWorkspaceCommandOptions{
        WID:          <workspace_id>,
        RefreshToken: core.StringPtr("refresh_token"),
    }
    
    applyResult, detailedResponse, err := schematicsService.ApplyWorkspaceCommand(applyWorkspaceCommandOptions)
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(applyResult, "", "  ")
    fmt.Println(string(w))
  • const params = {
      wId: '<workspace_id>',
      refreshToken: '<refresh_token>'',
    };
    
    schematicsService.applyWorkspaceCommand(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
          console.warn(err)
      });
  • workspace_activity_apply_result = schematics_service.apply_workspace_command(
        w_id='<workspace_id>',
        refresh_token='<refresh_token>'
    ).get_result()
    
    print(json.dumps(workspace_activity_apply_result, indent=2))
  • ApplyWorkspaceCommandOptions applyWorkspaceCommandOptions = new ApplyWorkspaceCommandOptions.Builder()
    .wId("<workspace_id>")
    .refreshToken("<refresh_token>")
    .build();
    
    Response<WorkspaceActivityApplyResult> response = service.applyWorkspaceCommand(applyWorkspaceCommandOptions).execute();
    WorkspaceActivityApplyResult workspaceActivityApplyResult = response.getResult();

Response

Response after successfully initiating a request to apply the Terraform template in IBM Cloud.

Status Code

  • Successfully ran a Schematics apply job 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.

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

  • Apply failed. Could not perform an apply job against the workspace. The workspace is frozen, or a Schematics create, update, plan, apply, destroy, delete, or refresh job has not completed yet. Unfreeze the workspace first or wait until the create, update, plan, apply, destroy, delete, or refresh job 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
  • {
      "activityid": "ec72d9e655e846bcbfbb840be49ef7bd"
    }

Perform a Schematics `destroy` job

Run a Schematics destroy job against your workspace. A destroy job removes all IBM Cloud resources that are associated with your workspace. Removing your resources does not delete the Schematics workspace. To delete the workspace, use the DELETE /v1/workspaces/{id} API. This API returns an activity or job ID that you use to retrieve the URL to the log file with the GET /v1/workspaces/{id}/actions/{action_id}/logs API.

Important: Your workspace must be in an Active, Failed, or Stopped state to perform a Schematics destroy job.

Note: Deleting IBM Cloud resources cannot be undone. Make sure that you back up any required data before you remove 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.

PUT /v1/workspaces/{w_id}/destroy

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace-resources.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.

    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.
  • The IAM delegated token for your IBM Cloud account. This token is required for requests that are sent via the UI only.

Path Parameters

  • The ID of the workspace for which you want to perform a Schematics destroy job. To find the workspace ID, use the GET /workspaces API.

Workspace destroy command options

  • curl -X PUT https://schematics.cloud.ibm.com/v1/workspaces/{id}/destroy -H "Authorization: Bearer <iam_token>" -H "refresh_token: <refresh_token>"
  • curl -X GET <log_url> -H "Authorization: Bearer <iam_token>"
  • destroyWorkspaceCommandOptions := &schematicsv1.DestroyWorkspaceCommandOptions{
        WID:          <workspace_id>,
        RefreshToken: core.StringPtr("refresh_token"),
    }
    
    destroyResult, detailedResponse, err := schematicsService.DestroyWorkspaceCommand(destroyWorkspaceCommandOptions)
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(destroyResult, "", "  ")
    fmt.Println(string(w))
  • const params = {
      wId: '<workspace_id>',
      refreshToken: '<refresh_token>',
    };
    
    schematicsService.destroyWorkspaceCommand(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • workspace_activity_destroy_result = schematics_service.destroy_workspace_command(
        w_id='<workspace_id>',
        refresh_token='<refresh_token>'
    ).get_result()
    
    print(json.dumps(workspace_activity_destroy_result, indent=2))
  • DestroyWorkspaceCommandOptions destroyWorkspaceCommandOptions = new DestroyWorkspaceCommandOptions.Builder()
    .wId("<workspace_id>")
    .refreshToken("<refresh_token>")
    .build();
    
    Response<WorkspaceActivityDestroyResult> response = service.destroyWorkspaceCommand(destroyWorkspaceCommandOptions).execute();
    WorkspaceActivityDestroyResult workspaceActivityDestroyResult = response.getResult();
    
    System.out.println(workspaceActivityDestroyResult);

Response

Response after successfully initiating a request to destroy the stack of resources provisioned using Terraform.

Status Code

  • Successfully initiated a Schematics destroy job 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.

  • Not found. The requested workspace cannot be located. Check that you have the correct workspace ID in your request. Or the requested state-file cannot be located. Run apply action to create a state-file.

  • Could not perform a destroy job against the workspace. The workspace is frozen, or a Schematics create, update, plan, apply, delete, destroy, or refresh job has not completed yet. Unfreeze the workspace first or wait until the create, update, plan, apply, delete, destroy, or refresh job 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
  • {
      "activityid": "12a111a1aa1111aaaaa123a11112222a11ß"
    }

Perform a Schematics `plan` job

Run a Schematics plan job against your workspace. The plan job creates a summary of IBM Cloud resources that must be created, modified, or deleted to achieve the state that is described in the Terraform or IBM Cloud catalog template that your workspace points to. During this time, you cannot make changes to your workspace. You can use the summary to verify your changes before you apply the template in IBM Cloud.

Important: Your workspace must be in an Inactive, Active, Failed, or Stopped state to perform a Schematics plan job.

Note: This API returns an activity or job ID that you use to retrieve the URL to the log file with the GET /v1/workspaces/{id}/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.

POST /v1/workspaces/{w_id}/plan

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace-resources.plan

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.

    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.
  • The IAM delegated token for your IBM Cloud account. This token is required for requests that are sent via the UI only.

Path Parameters

  • The ID of the workspace, for which you want to run a Schematics plan job. To find the ID of your workspace, use the GET /v1/workspaces API.

Workspace 'plan' job options

  • curl -X POST https://schematics.cloud.ibm.com/v1/workspaces/{id}/plan -H "Authorization: Bearer <iam_token>" -H "refresh_token: <refresh_token>"
  • curl -X GET <log_url> -H "Authorization: Bearer <iam_token>"
  • planWorkspaceCommandOptions := &schematicsv1.PlanWorkspaceCommandOptions{
        WID:          <workspace_id>,
        RefreshToken: core.StringPtr("refresh_token"),
    }
    
    planResult, detailedResponse, err := schematicsService.PlanWorkspaceCommand(planWorkspaceCommandOptions)
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(planResult, "", "  ")
    fmt.Println(string(w))
  • const params = {
      wId: '<workspace_id>',
      refreshToken: '<refresh_token>',
    };
    
    schematicsService.planWorkspaceCommand(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • workspace_activity_plan_result = schematics_service.plan_workspace_command(
        w_id='<workspace_id>',
        refresh_token='<refresh_token>'
    ).get_result()
    
    print(json.dumps(workspace_activity_plan_result, indent=2))
  • PlanWorkspaceCommandOptions planWorkspaceCommandOptions = new PlanWorkspaceCommandOptions.Builder()
    .wId("<workspace_id>")
    .refreshToken("<refresh_token>")
    .build();
    
    Response<WorkspaceActivityPlanResult> response = service.planWorkspaceCommand(planWorkspaceCommandOptions).execute();
    WorkspaceActivityPlanResult workspaceActivityPlanResult = response.getResult();
    
    System.out.println(workspaceActivityPlanResult);

Response

Response after successfully initiating a request to plan the Terraform template in IBM Cloud.

Status Code

  • Successfully performed a Schematics plan job.

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

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

  • 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
  • {
      "activityid": "f4091a17707d0433a3f9307e8bcbc853"
    }

Perform a Schematics `refresh` job

Run a Schematics refresh job against your workspace. A refresh job validates the IBM Cloud resources in your account against the state that is stored in the Terraform statefile of your workspace. If differences are found, the Terraform statefile is updated accordingly. This API returns an activity or job ID that you use to retrieve the URL to the log file with the GET /v1/workspaces/{id}/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.

PUT /v1/workspaces/{w_id}/refresh

Auditing

Calling this method generates the following auditing event.

  • schematics.workspace.refresh

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.

    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.
  • The IAM delegated token for your IBM Cloud account. This token is required for requests that are sent via the UI only.

Path Parameters

  • The ID of the workspace, for which you want to run a Schematics refresh job. To find the ID of your workspace, use the GET /v1/workspaces API.

  • curl -X PUT https://schematics.cloud.ibm.com/v1/workspaces/{id}/refresh -H "Authorization: Bearer <iam_token>" -H "refresh_token: <refresh_token>"
  • curl -X GET <log_url> -H "Authorization: Bearer <iam_token>"
  • refreshWorkspaceCommandOptions := &schematicsv1.RefreshWorkspaceCommandOptions{
        WID:          <workspace_id>,
        RefreshToken: core.StringPtr("refresh_token"),
    }
    
    refreshResult, detailedResponse, err := schematicsService.RefreshWorkspaceCommand(refreshWorkspaceCommandOptions)
    
    if err != nil {
        panic(err)
    }
    
    w, err := json.MarshalIndent(refreshResult, "", "  ")
    fmt.Println(string(w))
  • const params = {
      wId: '<workspace_id>',
      refreshToken: '<refresh_token>',
    };
    
    schematicsService.refreshWorkspaceCommand(params)
      .then(res => {
        console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
        console.warn(err)
      });
  • workspace_activity_refresh_result = schematics_service.refresh_workspace_command(
        w_id='<workspace_id>',
        refresh_token='<refresh_token>'
    ).get_result()
    
    print(json.dumps(workspace_activity_refresh_result, indent=2))
  • RefreshWorkspaceCommandOptions refreshWorkspaceCommandOptions = new RefreshWorkspaceCommandOptions.Builder()
    .wId("<workspace_id>")
    .refreshToken("<refresh_token>")
    .build();
    
    Response<WorkspaceActivityRefreshResult> response = service.refreshWorkspaceCommand(refreshWorkspaceCommandOptions).execute();
    WorkspaceActivityRefreshResult workspaceActivityRefreshResult = response.getResult();
    
    System.out.println(workspaceActivityRefreshResult);

Response

Response after successfully initiating a request to refresh the Terraform template in IBM Cloud.

Status Code

  • Successfully initiated a Schematics refresh job against your workspace.

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

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

  • Could not perform a refresh job against the workspace. The workspace is frozen, or a Schematics create, update, plan, apply, delete, destroy, or refresh job has not completed yet. Unfreeze the workspace first or wait until the create, update, plan, apply, delete, destroy, or refresh job completes before you try 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
  • {
      "activityid": "12a111a1aa1111aaaaa123a11112222a11"
    }

List jobs

Retrieve a list of all Schematics jobs. The job displays a list of jobs with the status as pending, in_progess, success, or failed. Jobs are generated when you use the POST /v2/jobs, PUT /v2/jobs/{job_id}, or DELETE /v2/jobs/{job_id}.

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/jobs

Auditing

Calling this method generates the following auditing event.

  • schematics.job.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]

  • Name of the resource (workspaces, actions, environment or controls)

    Allowable values: [workspaces,action,actions,environment]

  • The Resource Id. It could be an Action-id or Workspace-id.

  • Action Id

  • Workspace Id

  • list jobs

    Allowable values: [all]

  • curl --location --request GET https://schematics.cloud.ibm.com/v2/jobs?resource=actions&action_id=us-east.ACTION.Example-12a1b212.3287dc42  --header "Authorization: <access_token> " --header "Cookie: "
  • GetJobOptions getJobOptions = new GetJobOptions.Builder()
    .jobId("job ID")
    .build();
    
    Response<Job> response = service.getJob(getJobOptions).execute();
    Job job = response.getResult();
    
    System.out.println(job);
  • job_list = schematics_service.list_jobs().get_result()
    print(json.dumps(job_list, indent=2))
  • const params = {
    resource:"resource group name",
    actionId: "Users action ID"
    };
    
    schematicsService.listJobs(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
  • listJobsOptions := schematicsService.NewListJobsOptions()
    listJobsOptions.SetResource("set the action details")
    listJobsOptions.SetActionID("set the action ID")
    listJobsOptions.SetList("all")
    jobList, response, err := schematicsService.ListJobs(listJobsOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(jobList, "", "/v2/jobs/")
    fmt.Println(string(b))

Response

List of Job details

Status Code

  • Successfully listed the jobs 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
  • {
      "total_count": 2,
      "limit": 100,
      "offset": 0,
      "jobs": [
        {
          "id": "Users job ID",
          "name": "Users job name",
          "description": "Short description",
          "command_object": "Users resource action, for example, **action**",
          "command_object_id": "Users object ID",
          "command_name": "Users job command name, for example, **ansible_playbook_check**",
          "location": "Users location",
          "resource_group": "Users resource group name",
          "submitted_at": "2021-02-10T11:33:23.378Z",
          "duration": "57.243452S",
          "start_at": "2021-02-10T11:33:29.708Z",
          "end_at": "2021-02-10T11:34:26.951Z",
          "status": {
            "workspace_job_status": {
              "flow_status": {
                "updated_at": "1901-01-01T00:00:00.000Z"
              },
              "updated_at": "1901-01-01T00:00:00.000Z"
            },
            "action_job_status": {
              "action_name": "Users action name, for example, **00aaaa2222**",
              "status_code": "Job status ocde",
              "status_message": "Job status message",
              "updated_at": "1901-01-01T00:00:00.000Z"
            }
          },
          "log_summary": {
            "log_start_at": "1901-01-01T00:00:00.000Z",
            "log_analyzed_till": "1901-01-01T00:00:00.000Z",
            "repo_download_job": {},
            "workspace_job": {},
            "flow_job": {},
            "action_job": {
              "task_count": 3,
              "play_count": 1,
              "recap": {
                "unreachable": 1
              }
            }
          },
          "updated_at": "1901-01-01T00:00:00.000Z"
        }
      ]
    }

Create a job

Create & launch the Schematics job. It can be used to launch an Ansible playbook against a target hosts. The job displays a list of jobs with the status as pending, in_progess, success, or failed.

POST /v2/jobs

Auditing

Calling this method generates the following auditing event.

  • schematics.job.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 IAM refresh token for the user or service identity.

    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.

Create a Job Record and launch the Job

  • curl --location --request POST https://schematics.cloud.ibm.com/v2/jobs --header "Authorization: <access_token> "--header "Content-Type: application/json"--data-raw "{"command_object": "action","command_object_id": "us-east","command_name": "ansible_playbook_check","command_parameter": "site.yml"}"
  • CreateJobOptions createJobOptions = new CreateJobOptions.Builder()
    .refreshToken("testString")
    .commandObject("action")
    .commandObjectId("set your action ID.")
    .commandName("set command name")
    .commandParameter("aj.yml")
    .build();
    Response<Job> response = service.createJob(createJobOptions).execute();
    Job job = response.getResult();
    System.out.println(job);
  • job = schematics_service.create_job().get_result()
    object="action",
    object_id="Users action ID",
    name="ansible_playbook_run", parameter="test.yml"
    ).get_result()
    print(json.dumps(job, indent=2))
  • const params = {"refreshToken":"testString",
    "commandObject":"set your command object, [workspace or action]",
    "commandObjectId":"set your action ID",
    "commandName":"set your command, [ansible_playbook_run or ansible_playbook_check]",
    "commandParameter":"set playbook name with the extension, [test.yml]"
    };
    schematicsService.createJob(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
  • CreateJobOptions := schematicsService.NewCreateJobOptions("set your job options",)
    
    CreateJobOptions.SetCommandObject("set your command object, [workspace or action]")
    CreateJobOptions.SetCommandObjectID("set your action ID")
    CreateJobOptions.SetCommandName("set your command name")
    CreateJobOptions.SetCommandParameter("set your yml file as command parameter")
    
    job, response, err := schematicsService.CreateJob(CreateJobOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(job, "", "/v2/jobs")
    fmt.Println(string(b))

Response

Complete Job with user inputs and system generated data

Status Code

  • Successfully created the job in IBM Cloud Schematics.

  • 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 was not found

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

  • 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
  • {
      "command_object": "Users resource action, for example, **action**",
      "command_object_id": "Users job ID",
      "command_name": "Users job command name, for example, **ansible_playbook_check**",
      "command_parameter": "Users playbook name",
      "id": "Users job ID",
      "name": "Users job name",
      "description": "This Action Run Lamp on multiple host xxxx",
      "location": "Users location",
      "resource_group": "Users resource group name",
      "submitted_at": "2021-02-09T05:38:52.933Z",
      "submitted_by": "schematics@ibm.com",
      "start_at": "2021-02-09T05:38:52.933Z",
      "end_at": "1901-01-01T00:00:00.000Z",
      "status": {
        "workspace_job_status": {
          "flow_status": {
            "updated_at": "1901-01-01T00:00:00.000Z"
          },
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        "action_job_status": {
          "action_name": "Example-12ab2",
          "status_code": "job_pending",
          "status_message": "Job created and pending to start",
          "updated_at": "2021-02-09T05:38:52.933Z"
        }
      },
      "data": {
        "job_type": "",
        "workspace_job_data": {
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        "action_job_data": {
          "inputs": [
            {
              "name": "upassword",
              "value": "Abc@123xxx",
              "metadata": {
                "type": "string",
                "default_value": "Abc@123xxx",
                "secure": true
              }
            },
            {
              "name": "dbname",
              "value": "Users DB name",
              "metadata": {
                "type": "string",
                "default_value": "xxxx"
              }
            },
            {
              "name": "dbuser",
              "value": "Users DB user value",
              "metadata": {
                "type": "string",
                "default_value": "root"
              }
            },
            {
              "name": "mysql_port",
              "value": "Users MySQL port number",
              "metadata": {
                "type": "string",
                "default_value": "3306"
              }
            },
            {
              "name": "httpd_port",
              "value": "Users HTTP port number",
              "metadata": {
                "type": "string",
                "default_value": "80"
              }
            }
          ],
          "updated_at": "1901-01-01T00:00:00.000Z"
        }
      },
      "bastion": {
        "name": "bastionhost",
        "type": "string",
        "description": "string",
        "resource_query": "100.100.100.100",
        "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"
        }
      },
      "log_summary": {
        "log_start_at": "1901-01-01T00:00:00.000Z",
        "log_analyzed_till": "1901-01-01T00:00:00.000Z",
        "repo_download_job": {},
        "workspace_job": {},
        "flow_job": {},
        "action_job": {
          "recap": {}
        }
      },
      "updated_at": "1901-01-01T00:00:00.000Z"
    }

Get a job

Retrieve the detailed information of Job

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/jobs/{job_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.job.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

  • Job Id. Use GET /v2/jobs API to look up the Job Ids in your IBM Cloud account.

Query Parameters

  • Level of details returned by the get method

    Allowable values: [summary,detailed,ids]

  • curl --location --request GET https://schematics.cloud.ibm.com/v2/jobs/jobid --header "Authorization:  <access_token> "
  • GetJobOptions getJobOptions = new GetJobOptions.Builder()
    .jobId("set your job ID")
    .build();
    
    Response<Job> response = service.getJob(getJobOptions).execute();
    Job job = response.getResult();
    
    System.out.println(job);
  • job = schematics_service.get_job(job_id="us.JOB.keratinsample.08e45f87").get_result()
    print (json.dumps(job, indent=2))
  • const params = {jobId: "Users job ID"};
    
    schematicsService.getJob(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
  • getJobOptions := schematicsService.NewGetJobOptions("set job options",)
    getJobOptions.SetJobID("set your job ID")
    
    job, response, err := schematicsService.GetJob(getJobOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(job, "", "")
    fmt.Println(string(b))

Response

Complete Job with user inputs and system generated data

Status Code

  • Successfully retrieved details about your 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.

  • The specified resource was not found

  • 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": "Users job ID",
      "name": "Users Job name",
      "description": "Short description",
      "command_object": "Users resource action, for example, **action**",
      "command_object_id": "Users object ID",
      "command_name": "Users job command name, for example, **ansible_playbook_check**",
      "location": "Users location",
      "resource_group": "Users resource group",
      "submitted_at": "2021-02-09T05:38:52.933Z",
      "submitted_by": "users@test.com",
      "duration": "45.702379S",
      "start_at": "2021-02-09T05:38:58.338Z",
      "end_at": "2021-02-09T05:39:44.041Z",
      "status": {
        "workspace_job_status": {
          "flow_status": {
            "updated_at": "1901-01-01T00:00:00.000Z"
          },
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        "action_job_status": {
          "action_name": "Users action name",
          "status_code": "Users job status code",
          "status_message": "Users job execution status",
          "updated_at": "1901-01-01T00:00:00.000Z"
        }
      },
      "log_summary": {
        "log_start_at": "1901-01-01T00:00:00.000Z",
        "log_analyzed_till": "1901-01-01T00:00:00.000Z",
        "repo_download_job": {},
        "workspace_job": {},
        "flow_job": {},
        "action_job": {
          "task_count": 6,
          "play_count": 1,
          "recap": {
            "ok": 4,
            "failed": 1,
            "skipped": 1
          }
        }
      },
      "updated_at": "1901-01-01T00:00:00.000Z"
    }

Update a job

Creates a copy of the Schematics job and relaunches an existing job by updating the information of an existing Schematics job.

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 /v2/jobs/{job_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.job.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 IAM refresh token for the user or service identity.

    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

  • Job Id. Use GET /v2/jobs API to look up the Job Ids in your IBM Cloud account.

Clone the Job-record, and relaunch the Job

  • curl --location --request PUT https://schematics.cloud.ibm.com/v2/jobs/us-east.JOB.Example-12a1b212.6f314758 --header "Authorization: <access_token> "--header "Content-Type: application/json "--header "Cookie: "--data-raw "{ "command_object": "action",  "command_object_id": "us-east.ACTION.Example-12a1b212.3287dc42",  "command_name": "ansible_playbook_run",  "command_parameter": "site.yml"}"
  • ReplaceJobOptions replaceJobOptions = new ReplaceJobOptions.Builder()
    .refreshToken("testString")
    .jobId("set your job ID")
    .build();
    
    Response<Job> response = service.replaceJob(replaceJobOptions).execute();
    Job job = response.getResult();
    
    System.out.println(job);
  • job = schematics_service.replace_job(refresh_token='testString',
    job_id="set your job ID"
    ).get_result()
    print (json.dumps(job, indent=2))
  • const params = {
    refreshToken: 'testString',
    jobId: "Users job ID",
    description: "Very Huge short description",
    };
    
    schematicsService.replaceJob(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
  • UpdatejobOptions := schematicsService.NewReplaceJobOptions("teststring","teststring",)
    UpdatejobOptions.SetJobID("set the job ID")
    UpdatejobOptions.SetCommandObject("set your command object, [workspace or action] ")
    UpdatejobOptions.SetCommandObjectID("set your action ID")
    UpdatejobOptions.SetCommandName("set the command name")
    UpdatejobOptions.SetCommandParameter("set your yaml file for the command parameter")
    
    job, response, err := schematicsService.ReplaceJob(UpdatejobOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(job, "", "")
    fmt.Println(string(b))

Response

Complete Job with user inputs and system generated data

Status Code

  • Successfully relaunched the Job, returns a new Job Record

  • 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 was not found

  • The specified resource is locked, cannot be updated or deleted

  • 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
  • {
      "command_object": "Users resource action, for example, **action**",
      "command_object_id": "Users object ID",
      "command_name": "Users job command name, for example, **ansible_playbook_check**",
      "command_parameter": "Users playbook name",
      "id": "Users job ID",
      "name": "Users job name",
      "description": "Short description for the update",
      "location": "Users location",
      "resource_group": "Users resource group name",
      "submitted_at": "2021-02-10T11:33:23.378Z",
      "start_at": "2021-02-10T11:33:23.378Z",
      "end_at": "2021-02-09T05:39:44.041Z",
      "duration": "45.702379S",
      "status": {
        "workspace_job_status": {
          "flow_status": {
            "updated_at": "1901-01-01T00:00:00.000Z"
          },
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        "action_job_status": {
          "action_name": "Users action name, for example, **12ab2**",
          "status_code": "job_pending",
          "status_message": "Job created and pending to start",
          "updated_at": "2021-02-10T11:33:23.378Z"
        }
      },
      "data": {
        "job_type": "",
        "workspace_job_data": {
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        "action_job_data": {
          "updated_at": "1901-01-01T00:00:00.000Z"
        }
      },
      "bastion": {
        "name": "bastionhost",
        "type": "string",
        "description": "string",
        "resource_query": "100.100.100.100",
        "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"
        }
      },
      "log_summary": {
        "log_start_at": "1901-01-01T00:00:00.000Z",
        "log_analyzed_till": "1901-01-01T00:00:00.000Z",
        "repo_download_job": {},
        "workspace_job": {},
        "flow_job": {},
        "action_job": {
          "recap": {}
        }
      },
      "updated_at": "1901-01-01T00:00:00.000Z"
    }

Stop the running Job, and delete the Job

Stop the running Job, and delete the Job. 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 or update the action or 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.

DELETE /v2/jobs/{job_id}

Auditing

Calling this method generates the following auditing event.

  • schematics.job.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.

    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.
  • Equivalent to -force options in the command line

  • Auto propagate the chaange or deletion to the dependent resources

Path Parameters

  • Job Id. Use GET /v2/jobs API to look up the Job Ids in your IBM Cloud account.

  • curl --location --request DELETE https://schematics.cloud.ibm.com/v2/jobs/{jobid} --header "Authorization: <access_token> "
  • DeleteJobOptions deleteJobOptions = new DeleteJobOptions.Builder()
    .jobId("Set your job ID")
    .refreshToken("<refresh token>")
    .build();
    
    service.deleteJob(deleteJobOptions).execute();
  • response = schematics_service.delete_job(
    job_id="Set your job ID",
    refresh_token="<refresh token>"
    ).get_result()
    
    print(json.dumps(response, indent=2))
  • const params = {
    refreshToken: "Users refresh token",
    jobId: "Users job ID"
    };
    schematicsService.deleteJob(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
  • deleteJobOptions := schematicsService.NewDeleteJobOptions("testString","testString",)
    deleteJobOptions.SetJobID("set the job ID")
    response, err := schematicsService.DeleteJob(deleteJobOptions)
    if err != nil {
    panic(err)
    }

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.

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

Get job logs

Retrieve the job logs

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/jobs/{job_id}/logs

Auditing

Calling this method generates the following auditing event.

  • schematics.job.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

  • Job Id. Use GET /v2/jobs API to look up the Job Ids in your IBM Cloud account.

  • curl --location --request GET https://schematics.cloud.ibm.com/v2/jobs/{job_id}/logs --header "Authorization: <access_token>"
  • ListJobLogsOptions listJobLogsOptions = new ListJobLogsOptions.Builder()
    .jobId("job ID")
    .build();
    
    Response<JobLog> response = service.listJobLogs(listJobLogsOptions).execute();
    JobLog jobLog = response.getResult();
    
    System.out.println(jobLog);
  • job_log = schematics_service.list_job_logs(
    job_id="Set your job ID"
    ).get_result()
    
    print (job_log)
  • const params = {
    jobId: "Users job ID"
    };
    
    schematicsService.listJobLogs(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
  • listJobLogsOptions := schematicsService.NewListJobLogsOptions("testString",)
    listJobLogsOptions.SetJobID("set the job ID")
    jobLog, response, err := schematicsService.ListJobLogs(listJobLogsOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(jobLog, "", "")
    fmt.Println(string(b))

Response

Job Log details

Status Code

  • Successfully lists the jobs logs 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.

  • The specified resource was not found

  • 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 output files from the Job record

Get output files from the Job record. For more information, about the Schematics job status, download job logs, and download the output files, see Download Schematics Job.

GET /v2/jobs/{job_id}/files

Auditing

Calling this method generates the following auditing event.

  • schematics.job.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

  • Job Id. Use GET /v2/jobs API to look up the Job Ids in your IBM Cloud account.

Query Parameters

  • The type of file you want to download eg.state_file, plan_json.

    Allowable values: [template_repo,readme_file,log_file,state_file,plan_json]

  • curl --location --request GET http://schematics.cloud.ibm.com/v2/jobs/{job_id}/files?file_type=plan_json   --header "Authorization: <access_token> " --header "Cookie: "

Response

Output files from the Job record

Status Code

  • Successfully got the Job output files.

  • 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 was not found

  • 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
  • {
      "job_id": "36521f0bb4d5754366e41349a53385f7",
      "file_type": "plan_json",
      "file_content": "{\"format_version\":\"0.1\",\"terraform_version\":\"0.15.5\",\"variables\":{\"TF_VERSION\":{\"value\":0.13},\"image_id\":{\"value\":\"ami-1234\"},\"sample_var\":{\"value\":\"hello\"},\"sleepy_time\":{\"value\":0}},\"planned_values\":{\"outputs\":{\"rendered_template\":{\"sensitive\":false,\"value\":\"Hello, I am a template. My sample_var value = hello\"}},\"root_module\":{\"resources\":[{\"address\":\"null_resource.sleep\",\"mode\":\"managed\",\"type\":\"null_resource\",\"name\":\"sleep\",\"provider_name\":\"registry.terraform.io/hashicorp/null\",\"schema_version\":0}]}},\"resource_changes\":[{\"address\":\"null_resource.sleep\",\"mode\":\"managed\",\"type\":\"null_resource\",\"name\":\"sleep\",\"provider_name\":\"registry.terraform.io/hashicorp/null\",\"change\":{\"actions\":[\"create\"],\"before\":null,\"after\":{},\"after_unknown\":{\"id\":true,\"triggers\":true},\"before_sensitive\":false,\"after_sensitive\":{\"triggers\":{}}}}],\"output_changes\":{\"rendered_template\":{\"actions\":[\"create\"],\"before\":null,\"after\":\"Hello, I am a template. My sample_var value = hello\",\"after_unknown\":false,\"before_sensitive\":false,\"after_sensitive\":false}},\"prior_state\":{\"format_version\":\"0.1\",\"terraform_version\":\"0.15.5\",\"values\":{\"outputs\":{\"rendered_template\":{\"sensitive\":false,\"value\":\"Hello, I am a template. My sample_var value = hello\"}},\"root_module\":{\"resources\":[{\"address\":\"data.template_file.test\",\"mode\":\"data\",\"type\":\"template_file\",\"name\":\"test\",\"provider_name\":\"registry.terraform.io/hashicorp/template\",\"schema_version\":0,\"values\":{\"filename\":null,\"id\":\"16e936de6b5ccd5a7ecf3ad558469e38d9b234c28ac93e8076008334797e11de\",\"rendered\":\"Hello, I am a template. My sample_var value = hello\",\"template\":\"Hello, I am a template. My sample_var value = ${sample_var}\",\"vars\":{\"sample_var\":\"hello\"}}}]}}},\"configuration\":{\"provider_config\":{\"ibm\":{\"name\":\"ibm\",\"version_constraint\":\"1.13.1\"}},\"root_module\":{\"outputs\":{\"rendered_template\":{\"expression\":{\"references\":[\"data.template_file.test\"]}}},\"resources\":[{\"address\":\"null_resource.sleep\",\"mode\":\"managed\",\"type\":\"null_resource\",\"name\":\"sleep\",\"provider_config_key\":\"null\",\"provisioners\":[{\"type\":\"local-exec\",\"expressions\":{\"command\":{\"references\":[\"var.sleepy_time\"]}}}],\"expressions\":{\"triggers\":{}},\"schema_version\":0},{\"address\":\"data.template_file.test\",\"mode\":\"data\",\"type\":\"template_file\",\"name\":\"test\",\"provider_config_key\":\"template\",\"expressions\":{\"template\":{\"constant_value\":\"Hello, I am a template. My sample_var value = ${sample_var}\"},\"vars\":{\"references\":[\"var.sample_var\"]}},\"schema_version\":0}],\"variables\":{\"TF_VERSION\":{\"default\":0.13,\"description\":\"terraform version.\"},\"image_id\":{\"description\":\"The id of the machine image (AMI) to use for the server.\"},\"sample_var\":{\"default\":\"hello\",\"description\":\"A sample_var to pass to the template.\"},\"sleepy_time\":{\"default\":0,\"description\":\"How long our local-exec will take a nap.\"}}}}}\n",
      "updated_at": "2022-03-30T07:17:57.503Z"
    }

Delete one or more workspace

Delete one or multiple Schematics workspace. Deleting a workspace does not destroy the resources from the Schematics 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.

POST /v1/workspace_jobs

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.

    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.

Create a workspace deletion job

  • curl --location --request POST  https://us-east.schematics.cloud.ibm.com/v1/workspace_jobs --header "Content-Type: application/json" --header "Authorization: <access_token> " --data-raw "{"workspaces": ["us-south.workspace.testWorkspace.a6010c37","us-south.workspace.teraformNewupdatedone.72011986","us-south.workspace.readterraform.400b427c","us-south.workspace.myworkspacesink.49745827","us-south.workspace.ReadTerraformTemp.c98c9774","us-south.workspace.SampleTest1.2a51c3a1"],"job": "delete"}"
  • workspace_bulk_delete_response = schematics_service.create_workspace_deletion_job(
    new_workspaces=["us-south.workspace.bulkjob-wstesttestpart3.e64bbec8","us-south.workspace.bulkjob-wstesttestpart4.7982dc4a"],
    refresh_token='testString'
    ).get_result()
    print(json.dumps(workspace_bulk_delete_response, indent=2))
    
  • List list = new ArrayList();
    list.add("us-south.workspace.bulkjob-wstesttestpart11.f70eba3e");
    list.add(1,"us-south.workspace.bulkjob-wstesttestpart12.4a6a7fda");
    CreateWorkspaceDeletionJobOptions createWorkspaceDeletionJobOptions = new CreateWorkspaceDeletionJobOptions.Builder()
    .newWorkspaces(list)
    .refreshToken("testString")
    .build();
    Response<WorkspaceBulkDeleteResponse> response = service.createWorkspaceDeletionJob(createWorkspaceDeletionJobOptions).execute();
    WorkspaceBulkDeleteResponse workspaceBulkDeleteResponse = response.getResult();
    System.out.println(workspaceBulkDeleteResponse);
    
  • const params = {
    newWorkspaces:['us-south.workspace.bulkjob-wstesttestpart7.233b36b2','us-south.workspace.bulkjob-wstesttestpart8.e5b68c1e'],
    job:'Delete',
    refreshToken: 'testString',
    };
    schematicsService.createWorkspaceDeletionJob(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
    
  • createWorkspaceDeletionJobOptions := schematicsService.NewCreateWorkspaceDeletionJobOptions("teststring")
    deleteworkspace := []string{"us-south.workspace.bulkjob-wstesttestpart15.b9030d37", "us-south.workspace.bulkjob-wstesttestpart16.3a4a2888"}
    createWorkspaceDeletionJobOptions.SetNewWorkspaces(deleteworkspace)
    createWorkspaceDeletionJobOptions.SetNewJob("delete")
    workspaceBulkDeleteResponse, response, err := schematicsService.CreateWorkspaceDeletionJob(createWorkspaceDeletionJobOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(workspaceBulkDeleteResponse, "", "  ")
    fmt.Println(string(b))
    fmt.Println(response)
    

Response

The response after successfully initiating the bulk job to delete multiple workspaces

Status Code

  • Successfully initiated the workspace deletion.

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

Example responses
  • {
      "job_id": "d16bd5fe2e86886026b8e2ebea3da0e9",
      "job": "delete"
    }

Get the workspace deletion job status

Retrieve detailed information for a workspace deletion job status.

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/workspace_jobs/{wj_id}/status

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 workspace job ID.

  • curl --location --request GET  https://us-east.schematics.cloud.ibm.com/v1/workspace_jobs/be81cdf8e030ddf07a747c7aa2adcfda/status --header "Content-Type: application/json" --header "Authorization: <access_token> " --header "Cookie: " --data-raw 
  • workspace_job_response = schematics_service.get_workspace_deletion_job_status(
    wj_id='<job_id>'
    ).get_result()
    print(json.dumps(workspace_job_response, indent=2))
    
  • GetWorkspaceDeletionJobStatusOptions getWorkspaceDeletionJobStatusOptions = new GetWorkspaceDeletionJobStatusOptions.Builder()
    .wjId("<job_id>")
    .build();
    Response<WorkspaceJobResponse> response = service.getWorkspaceDeletionJobStatus(getWorkspaceDeletionJobStatusOptions).execute();
    WorkspaceJobResponse workspaceJobResponse = response.getResult();
    System.out.println(workspaceJobResponse);
    
  • const params = {
    wjId: '<job_id>',
    };
    schematicsService.getWorkspaceDeletionJobStatus(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
    
  • getWorkspaceDeletionJobStatusOptions := schematicsService.NewGetWorkspaceDeletionJobStatusOptions(
    "testString",
    )
    getWorkspaceDeletionJobStatusOptions.SetWjID("<job_id>")
    workspaceJobResponse, response, err := schematicsService.GetWorkspaceDeletionJobStatus(getWorkspaceDeletionJobStatusOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(workspaceJobResponse, "", "  ")
    fmt.Println(string(b))
    fmt.Println(response)
    

Response

The response from the workspace bulk job status.

Status Code

  • Successfully retrieved details about your workspace deletion 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.

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

Example responses
  • {
      "job_status": {
        "last_updated_on": "2021-09-24T05:46:23.266Z",
        "success": [
          "us-south.workspace.bulkjob-wstesttestpart1.c67ba74d",
          "us-south.workspace.bulkjob-wstesttestpart2.11bdd6e7"
        ],
        "failed": [
          "us-south.workspace.testWorkspace.a6010c37"
        ]
      }
    }

List inventory definitions

Retrieve a list of all Schematics inventories 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 inventories that are created in us-south or us-east are retrieved. For more information, about supported API endpoints, see APIendpoints.

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/inventories

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/inventories --header "Content-Type: application/json" --header "Authorization: <access_token> " --data-raw "{"name": "dev-inventory538","description": "My dev env inventory","location": "us-east","resource_group": "Default",,"inventories_ini": "[windows] \n 158.177.7.181"}
  • inventory_resource_record_list = schematics_service.list_inventories().get_result()
    print(json.dumps(inventory_resource_record_list, indent=2))
    
  • ListInventoriesOptions listInventoriesOptions = new ListInventoriesOptions.Builder()
    .build();
    Response<InventoryResourceRecordList> response = service.listInventories(listInventoriesOptions).execute();
    InventoryResourceRecordList inventoryResourceRecordList = response.getResult();
    System.out.println(inventoryResourceRecordList);
    
  • schematicsService.listInventories({})
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
    
  • listInventoriesOptions := schematicsService.NewListInventoriesOptions()
    inventoryResourceRecordList, response, err := schematicsService.ListInventories(listInventoriesOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(inventoryResourceRecordList, "", "  ")
    fmt.Println(string(b))
    fmt.Println(response)
    

Response

List of Inventory definition records

Status Code

  • Successful listed all inventory definition resources

  • 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
  • {
      "total_count": 24,
      "limit": 100,
      "offset": 0,
      "inventories": [
        {
          "name": "resourcename",
          "id": ".INVENTORY.resourcename.218b1903",
          "created_at": "2021-03-13T16:34:34.709Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "resourcename1",
          "id": ".INVENTORY.resourcename.a5857cd4",
          "created_at": "2021-03-15T10:17:35.244Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "abcdinv11",
          "id": "us-south.INVENTORY.abcdinv11.57fe6b53",
          "description": "My description",
          "location": "us-east",
          "resource_group": "Default",
          "created_at": "2021-03-26T04:13:55.591Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "abcdinv13",
          "id": "us-south.INVENTORY.abcdinv11.72794f6d",
          "description": "My description",
          "location": "us-east",
          "resource_group": "Default",
          "created_at": "2021-03-25T11:29:03.692Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "2021-03-25T12:25:29.815Z",
          "updated_by": "schematics@ibm.com"
        },
        {
          "name": "abcdinv4",
          "id": "us-south.INVENTORY.abcdinv4.d0b2201d",
          "description": "My description",
          "location": "us-south",
          "resource_group": "Default",
          "created_at": "2021-03-25T04:28:08.360Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "abcdinv5",
          "id": "us-east.INVENTORY.abcdinv5.ae1247ee",
          "description": "My description",
          "location": "us-south",
          "resource_group": "Default",
          "created_at": "2021-03-25T04:28:31.944Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "abcdinv6",
          "id": "us-east.INVENTORY.abcdinv6.b7646b3f",
          "description": "My description",
          "location": "us-east",
          "resource_group": "Default",
          "created_at": "2021-03-25T04:30:31.619Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "abcdinv7",
          "id": "us-east.INVENTORY.abcdinv7.588385ed",
          "description": "My description",
          "location": "us-east",
          "resource_group": "Default",
          "created_at": "2021-03-25T04:30:58.130Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "abcdinv8",
          "id": "us-east.INVENTORY.abcdinv8.3608dd80",
          "description": "My description",
          "location": "us-east",
          "resource_group": "Default",
          "created_at": "2021-03-25T04:32:25.431Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "abcdinv9",
          "id": "us-east.INVENTORY.abcdinv9.54ef1de5",
          "description": "My description",
          "location": "us-east",
          "resource_group": "Default",
          "created_at": "2021-03-25T04:33:09.774Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "dev-inventory527",
          "id": "us-east.INVENTORY.dev-inventory527.35cefc61",
          "description": "My dev env inventory",
          "location": "us-east",
          "resource_group": "Default",
          "created_at": "2021-03-22T09:28:09.172Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "dev-inventory5279",
          "id": "us-east.INVENTORY.dev-inventory5279.5024cb04",
          "description": "My dev env inventory",
          "location": "us-east",
          "resource_group": "Default",
          "created_at": "2021-03-24T10:06:54.248Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "dev-inventory52d7",
          "id": "us-east.INVENTORY.dev-inventory52d7.c401d447",
          "description": "My dev env inventory",
          "location": "us-east",
          "resource_group": "Default",
          "created_at": "2021-03-22T09:37:38.070Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "dev-inventory52d7p",
          "id": "us-east.INVENTORY.dev-inventory52d7p.972abfb3",
          "description": "My dev env inventory",
          "location": "us-east",
          "resource_group": "Default",
          "created_at": "2021-03-22T10:07:47.985Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "dev-inventory531",
          "id": "us-east.INVENTORY.dev-inventory531.1f67f6da",
          "description": "My dev env inventory",
          "location": "us-east",
          "resource_group": "Default",
          "created_at": "2021-03-25T04:21:09.116Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "dev-inventory532",
          "id": "us-east.INVENTORY.dev-inventory532.3625125f",
          "description": "My dev env inventory",
          "location": "us-east",
          "resource_group": "Default",
          "created_at": "2021-03-25T04:21:31.918Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "dev-inventory538",
          "id": "us-east.INVENTORY.dev-inventory538.1ba768aa",
          "description": "My dev env inventory",
          "location": "us-east",
          "resource_group": "Default",
          "created_at": "2021-03-26T07:08:00.264Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "dev-inventory5d28d7p",
          "id": "us-east.INVENTORY.dev-inventory5d28d7p.1e90678d",
          "description": "My dev env inventory",
          "location": "us-east",
          "resource_group": "Default",
          "created_at": "2021-03-22T11:10:12.608Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "dev-inventory5d2d7p",
          "id": "us-east.INVENTORY.dev-inventory5d2d7p.38815610",
          "description": "My dev env inventory",
          "location": "us-east",
          "resource_group": "Default",
          "created_at": "2021-03-22T10:15:46.185Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "dev-inventory",
          "id": "us-east.INVENTORY.dev-inventory.160c6d33",
          "description": "My dev env inventory",
          "location": "us-east",
          "resource_group": "Default",
          "created_at": "2021-03-11T10:49:31.707Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "dev-inventory1",
          "id": "us-east.INVENTORY.dev-inventory1.5e8f5354",
          "description": "My dev env inventory",
          "location": "us-east",
          "resource_group": "Default",
          "created_at": "2021-03-15T10:56:10.415Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "string",
          "id": "us-east.INVENTORY.string.9476a5b3",
          "description": "string",
          "location": "us-east",
          "resource_group": "string",
          "created_at": "2021-03-09T04:07:56.153Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "string",
          "id": "us-east.INVENTORY.string.de4b951c",
          "description": "string",
          "location": "us-east",
          "resource_group": "string",
          "created_at": "2021-03-10T17:29:24.274Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "string",
          "id": "us-east.INVENTORY.string.f1ef1a24",
          "description": "string",
          "location": "us-east",
          "resource_group": "string",
          "created_at": "2021-03-09T06:19:30.865Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "name": "dev-inventoryapidocexample",
          "id": "us-east.INVENTORY.dev-inventoryapidocexample.21788a22",
          "description": "My cloud linux inventory",
          "location": "us-east",
          "resource_group": "Default",
          "created_at": "2021-09-29T11:44:58.527Z",
          "created_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        }
      ]
    }

Create an inventory definition

Create an IBM Cloud Schematics inventory as a single IBM Cloud resource where you want to run Ansible playbook by using Schematics actions. For more information, about inventory host groups, refer to creating static and dynamic inventory for Schematics actions.

Note you cannot update the location and region, resource group once an action is created. Also, make sure your IP addresses are in the allowlist. If your Git repository already contains a host file. Schematics does not overwrite the host file already present in your Git repository.

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/inventories

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.

Create a Inventory definition resource

  • curl --location --request POST https://schematics.cloud.ibm.com/v2/inventories --header Authorization: <access_token> " --header "Content-Type: application/json" '{"name": "dev-inventoryapidocexample", "description": "My cloud linux inventory","location": "us-east", "resource_group": "Default","inventories_ini": "[windows] \n 158.177.7.181"}'
  • inventory_resource_record = schematics_service.create_inventory(
    name= "dev-inventory542",
    description= "My dev env inventory",
    location= "us-east",
    resource_group= "Default",
    resource_queries= ["default.RESOURCEQUERY.string.df3d8a47"]
    ).get_result()
    print(json.dumps(inventory_resource_record, indent=2))
    
  • CreateInventoryOptions createInventoryOptions = new CreateInventoryOptions.Builder()
    .name("dev-inventory506")
    .description("My dev env inventory")
    .location("us-east")
    .build();
    Response<InventoryResourceRecord> response = service.createInventory(createInventoryOptions).execute();
    InventoryResourceRecord inventoryResourceRecord = response.getResult();
    System.out.println(inventoryResourceRecord);
    
  • const params = {
    name: "dev-inventory506",
    description: "My dev env inventory",
    location: "us-east",
    resource_group: "Default",
    resource_queries: ["default.RESOURCEQUERY.string.df3d8a47"]};
    schematicsService.createInventory(params)
    .then(res => {console.log(JSON.stringify(res.result, null, 2));})
    .catch(err => {
    console.warn(err)
    });
    
  • createInventoryOptions := schematicsService.NewCreateInventoryOptions()
    createInventoryOptions.SetName("dev-inventory542")
    createInventoryOptions.SetDescription("My dev env inventory")
    createInventoryOptions.SetLocation("us-east")
    inventoryResourceRecord, response, err := schematicsService.CreateInventory(createInventoryOptions)
    if err != nil {
    panic(err)
    }
    fmt.Println(response)
    b, _ := json.MarshalIndent(inventoryResourceRecord, "", "")
    fmt.Println(string(b))
    

Response

Complete inventory definition details

Status Code

  • Successfully created Inventory definition resource

  • 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

  • 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": "dev-inventoryapidocexample",
      "id": "us-east.INVENTORY.dev-inventoryapidocexample.21788a22",
      "description": "My cloud linux inventory",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-09-29T11:44:58.527Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "1901-01-01T00:00:00.000Z",
      "inventories_ini": "[windows] \n158.177.7.181                        "
    }

Get an inventory definition

Use this API to retrieve the detailed information for a resource inventory definition used to target an action in your IBM Cloud account. For more information, about inventory get, refer to ibmcloud schematics inventory get.

Note you can fetch only the location and region, resource group from where your inventory 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.

GET /v2/inventories/{inventory_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

  • Resource Inventory Id. Use GET /v2/inventories API to look up the Resource Inventory definition Ids in your IBM Cloud account.

Query Parameters

  • Level of details returned by the get method

    Allowable values: [summary,detailed,ids]

  • curl --location --request GET https://schematics.cloud.ibm.com/v2/inventories/{inventory_id} —header "Authorization:  <access_token> " —header "Content-Type: application/json "
  • curl --location --request GET curl -X GET \ https://schematics.cloud.ibm.com/v2/inventories/{inventory_id}?profile=detailed —header "Authorization:  <access_token> " —header "Content-Type: application/json "                    
  • inventory_resource_record = schematics_service.get_inventory(
    inventory_id='set an inventory ID'
    ).get_result()
    print(json.dumps(inventory_resource_record, indent=2))
    
  • GetInventoryOptions getInventoryOptions = new GetInventoryOptions.Builder()
    .inventoryId("set an inventory Id")
    .build();
    Response<InventoryResourceRecord> response = service.getInventory(getInventoryOptions).execute();
    InventoryResourceRecord inventoryResourceRecord = response.getResult();
    System.out.println(inventoryResourceRecord);
    
  • const params = {inventoryId: 'set an inventory ID',};
    schematicsService.getInventory(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
    
  • getInventoryOptions := schematicsService.NewGetInventoryOptions(
    testString)
    getInventoryOptions.SetInventoryID("set an inventory ID")
    inventoryResourceRecord, response, err := schematicsService.GetInventory(getInventoryOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(inventoryResourceRecord, "", "  ")
    fmt.Println(string(b))
    fmt.Println(response)
    

Response

Complete inventory definition details

Status Code

  • Successfully retrieved the resource inventory 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 was not found

  • 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": "dev-inventoryapidocexample",
      "id": "us-east.INVENTORY.dev-inventoryapidocexample.21788a22",
      "description": "My Example cloud linux inventory",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-09-29T11:44:58.527Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "2021-09-29T15:05:19.550Z",
      "updated_by": "schematics@ibm.com",
      "inventories_ini": "[windows] \n158.177.7.181                                                "
    }

Update an inventory definition

Use this API to update the inventory definition resource used to target an action. For more information, about inventory update, refer to ibmcloud schematics inventory update.

Note you cannot update the location and region, resource group 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.

PUT /v2/inventories/{inventory_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

  • Resource Inventory Id. Use GET /v2/inventories API to look up the Resource Inventory definition Ids in your IBM Cloud account.

Update the inventory definition resource

  • curl --location --request PUT https://schematics.cloud.ibm.com/v2/inventories/us-east.INVENTORY.dev-inventory538.1ba768aa/ --header "Content-Type: application/json" --header "Authorization: <access_token> " --data-raw "{"name": "MainFrame-dev-inve","description": "My dev env inventory","location": "us-east","resource_group": "Default","inventories_ini": "[windows] \n 158.177.7.181"}
  • inventory_resource_record = schematics_service.replace_inventory(
    inventory_id='us-east.INVENTORY.dev-inventory542.475e3f27',
    name="dev-inventory542",
    description="My dev env inventory text is replaced",
    location="us-east",
    resource_group= "Default",
    resource_queries= ["default.RESOURCEQUERY.string.df3d8a47"]
    ).get_result()
    print(json.dumps(inventory_resource_record, indent=2))
    
  • ReplaceInventoryOptions replaceInventoryOptions = new ReplaceInventoryOptions.Builder()
    .inventoryId("set an inventory Id")
    .name("dev-inventory516")
    .description("My dev env inventory is Java updated")
    .location("us-east")
    .build();
    Response<InventoryResourceRecord> response = service.replaceInventory(replaceInventoryOptions).execute();
    InventoryResourceRecord inventoryResourceRecord = response.getResult();
    System.out.println(inventoryResourceRecord);
    
  • const params = {
    inventoryId: 'set an inventory ID',
    name:"dev-inventory",
    description: "My dev env inventory New Example",
    location: "us-east",
    resource_group: "Default",
    resource_queries: ["default.RESOURCEQUERY.string.df3d8a47"]
    };
    schematicsService.replaceInventory(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
    
  • replaceInventoryOptions := schematicsService.NewReplaceInventoryOptions(
    testString)
    replaceInventoryOptions.SetInventoryID("set your inventory ID")
    replaceInventoryOptions.SetName("dev-inventory548")
    replaceInventoryOptions.SetDescription("My dev env inventory is correct")
    replaceInventoryOptions.SetLocation("us-east")
    inventoryResourceRecord, response, err := schematicsService.ReplaceInventory(replaceInventoryOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(inventoryResourceRecord, "", "  ")
    fmt.Println(string(b))
    fmt.Println(response)
    

Response

Complete inventory definition details

Status Code

  • Successfully updated the inventory definition resource

  • 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 was not found

  • The specified resource is locked, cannot be updated or deleted

  • 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": "dev-inventoryapidocexample",
      "id": "us-east.INVENTORY.dev-inventoryapidocexample.21788a22",
      "description": "My Example cloud linux inventory",
      "location": "us-east",
      "resource_group": "Default",
      "created_at": "2021-09-29T11:44:58.527Z",
      "created_by": "schematics@ibm.com",
      "updated_at": "2021-09-29T15:05:19.550Z",
      "updated_by": "schematics@ibm.com",
      "inventories_ini": "[windows] \n158.177.7.181"
    }

Delete an inventory definition

Use this API to delete the resource inventory definition by using the inventory ID that you want to run against. For more information, about inventory delete, refer to ibmcloud schematics inventory delete.

Note you cannot delete the location and region, resource group from where your inventory 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.

DELETE /v2/inventories/{inventory_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.

  • Equivalent to -force options in the command line

  • Auto propagate the chaange or deletion to the dependent resources

Path Parameters

  • Resource Inventory Id. Use GET /v2/inventories API to look up the Resource Inventory definition Ids in your IBM Cloud account.

  • curl --location --request DELETE https://schematics.cloud.ibm.com/v2/inventories/us-east.INVENTORY.dev-inventory523.244223cf/  --header "Content-Type: application/json" --header "Authorization: <access_token> " --data-raw "{"name": "dev-inventory538","description": "My dev env inventory","location": "us-east","resource_group": "Default","resource_queries": ["default.RESOURCEQUERY.string.df3d8a47"]}
  • response = schematics_service.delete_inventory(
    inventory_id='us-east.INVENTORY.dev-inventory502.e383dcbb'
    ).get_result()
    print(json.dumps(response, indent=2))
    
  • DeleteInventoryOptions deleteInventoryOptions = new DeleteInventoryOptions.Builder()
    .inventoryId("set an inventory Id")
    .build();
    service.deleteInventory(deleteInventoryOptions).execute();
    
  • const params = {
    inventoryId: 'set an inventory ID',
    };
    schematicsService.deleteInventory(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
    
  • deleteInventoryOptions := schematicsService.NewDeleteInventoryOptions(
    testString)
    deleteInventoryOptions.SetInventoryID("set inventory Id")
    response, err := schematicsService.DeleteInventory(deleteInventoryOptions)
    if err != nil {
    panic(err)
    }
    fmt.Println(response)
    

Response

Status Code

  • Successfully deleted the resource inventory 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.

  • The specified resource was not found

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

  • 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 resource queries

Retrieve the list of resource query definitions that you have access to. The list of resource queries 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 resource query definitions 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/resources_query

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/resources_query/ --header "Authorization: <access_token>" --header "Content-Type: application/json" --header "Cookie: " --data-raw "
  • resource_query_record_list = schematics_service.list_resource_query().get_result()
    print(json.dumps(resource_query_record_list, indent=2))
    
  • ListResourceQueryOptions listResourceQueryOptions = new ListResourceQueryOptions.Builder()
    .build();
    Response<ResourceQueryRecordList> response = service.listResourceQuery(listResourceQueryOptions).execute();
    ResourceQueryRecordList resourceQueryRecordList = response.getResult();
    System.out.println(resourceQueryRecordList);
    
  • schematicsService.listResourceQuery({})
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
    
  • listResourceQueryOptions := schematicsService.NewListResourceQueryOptions()
    resourceQueryRecordList, response, err := schematicsService.ListResourceQuery(listResourceQueryOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(resourceQueryRecordList, "", "  ")
    fmt.Println(string(b))
    fmt.Println(response)
    

Response

List of Resource query records

Status Code

  • Successful listed all resource query definitions

  • 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
  • {
      "total_count": 4,
      "limit": 100,
      "offset": 0,
      "ResourceQueries": [
        {
          "id": "default.RESOURCEQUERY.a12344",
          "created_at": "2021-04-09T10:05:33.073Z",
          "created_by": "user@in.ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        },
        {
          "type": "vsi",
          "name": "demorqcli",
          "id": "default.RESOURCEQUERY.demorqcli.79f53cb8",
          "created_at": "2021-03-31T06:25:27.675Z",
          "created_by": "user@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z",
          "queries": [
            {
              "query_type": "workspaces",
              "query_condition": [
                {
                  "name": "workspace-id",
                  "value": "us-east.workspace.sundeepKfreporttest.22e234125",
                  "description": "string"
                },
                {
                  "name": "resource-name",
                  "value": "tf44234vpc-pubpriv-frontend-vsi",
                  "description": "string"
                }
              ]
            }
          ]
        },
        {
          "type": "workspace_resource",
          "name": "hello",
          "id": "default.RESOURCEQUERY.hello.2f12312",
          "created_at": "2021-04-09T10:20:06.572Z",
          "created_by": "user@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z",
          "queries": [
            {
              "query_type": "workspaces",
              "query_condition": [
                {
                  "name": "workspace-id",
                  "value": "us-east.ACTION.kubectlWorkshop.1010101",
                  "description": "string"
                },
                {
                  "name": "resource-name",
                  "value": "123vpc-pubpriv-frontend-vsi",
                  "description": "string"
                }
              ]
            }
          ]
        },
        {
          "type": "workspaces",
          "name": "samplequerytest",
          "id": "t12312121vpc-pubpriv-frontend-vsi",
          "created_at": "2021-03-31T06:32:54.065Z",
          "created_by": "user@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z"
        }
      ]
    }

Create resource query

Use this API to create a resource query definition that will be used to select an IBM Cloud resource or a group of resources as the dynamic inventory for the Schematics Actions. For more information, about resource query commands, refer to ibmcloud schematics resource query create. Note you cannot update the location and region, resource group once an action is created. Also, make sure your IP addresses are in the allowlist. If your Git repository already contains a host file. Schematics does not overwrite the host file already present in your Git repository.

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/resources_query

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.

Create a resource query definition

  • curl --location --request POST https://schematics.cloud.ibm.com/v2/resources_query/ --header "Authorization: <access_token> "  --header "Content-Type: application/json"  --header "Cookie:" --data-raw "{"type": "workspace_resource","name": "hello","queries": [{"query_type": "workspaces","query_condition": [{"name": "workspace-id", "value": "us-east.ACTION.kubectlWorkshop.41901417","description": "string"},{"name": "resource-name","value": "tf00vpc-pubpriv-frontend-vsi","description": "string"}]}]}'
  • resource_query_record = schematics_service.create_resource_query(
    type="workspace_resource",
    name="hello my world",
    queries=[{
    query_type:"workspaces",
    query_condition: [{
    name:"workspace-id",
    value:"us-east.ACTION.kubectlWorkshop.41901417",
    description:"string"},{
    name:"resource-name",
    value:"tf00vpc-pubpriv-frontend-vsi",
    description:"string"}
    ]
    }
    ]
    ).get_result()
    print(json.dumps(resource_query_record, indent=2))
  • CreateResourceQueryOptions createResourceQueryOptions = new CreateResourceQueryOptions.Builder()
    .type("workspace_resource")
    .name("hello my world")
    .build();
    Response<ResourceQueryRecord> response = service.createResourceQuery(createResourceQueryOptions).execute();
    ResourceQueryRecord resourceQueryRecord = response.getResult();
    System.out.println(resourceQueryRecord);
    
  • const params = {
    type: "workspace_resource",
    name: "hello my world",
    queries: [
    {
    query_type: "workspaces",
    query_condition: [
    {name: "workspace-id",value: "us-east.ACTION.kubectlWorkshop.41901417",description: "string"},
    {name: "resource-name",value: "tf00vpc-pubpriv-frontend-vsi",description: "string"}
    ]}]};
    schematicsService.createResourceQuery(params)
    .then(res => {console.log(JSON.stringify(res.result, null, 2));})
    .catch(err => {console.warn(err)});
    
  • createResourceQueryOptions := schematicsService.NewCreateResourceQueryOptions()
    createResourceQueryOptions.SetType("workspace_resource")
    createResourceQueryOptions.SetName("hello")
    resourceQueryRecord, response, err := schematicsService.CreateResourceQuery(createResourceQueryOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(resourceQueryRecord, "", "  ")
    fmt.Println(string(b))
    fmt.Println(response)
    

Response

Describe resource query record

Status Code

  • Successfully created resource query 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

  • 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": "workspace_resource",
      "name": "hello",
      "id": "your resource query ID.",
      "created_at": "2021-04-09T10:20:06.572Z",
      "created_by": "usera@ibm.com",
      "updated_at": "1901-01-01T00:00:00.000Z",
      "queries": [
        {
          "query_type": "workspaces",
          "query_condition": [
            {
              "name": "workspace-id",
              "value": "us-east.ACTION.kubectlWorkshop.1010101",
              "description": "string"
            },
            {
              "name": "resource-name",
              "value": "t123vpc-pubpriv-frontend-vsi",
              "description": "string"
            }
          ]
        }
      ]
    }

Get resources query

Use this API to retrieve the information resource query by Id. For more information, about resource query commands, refer to ibmcloud schematics resource query get.

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/resources_query/{query_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

  • Resource query Id. Use GET /v2/resource_query API to look up the Resource query definition Ids in your IBM Cloud account.

  • curl --location --request GET https://schematics.cloud.ibm.com/v2/resources_query/default.RESOURCEQUERY.hello.2fdda8ce --header "Authorization: <access_token>"  --header "Content-Type: application/json" --header "Cookie: " --data-raw "
  • GetResourcesQueryOptions getResourcesQueryOptions = new GetResourcesQueryOptions.Builder()
    .queryId("set a query Id")
    .build();
    Response<ResourceQueryRecord> response = service.getResourcesQuery(getResourcesQueryOptions).execute();
    ResourceQueryRecord resourceQueryRecord = response.getResult();
    System.out.println(resourceQueryRecord);
    
  • resource_query_record = schematics_service.get_resources_query(
    query_id='default.RESOURCEQUERY.hello-my-world.c1789bc1'
    ).get_result()
    print(json.dumps(resource_query_record, indent=2))
    
  • const params = {
    queryId: 'set a resource-query Id',
    };
    schematicsService.getResourcesQuery(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
    
  • getResourcesQueryOptions := schematicsService.NewGetResourcesQueryOptions(
    testString)
    getResourcesQueryOptions.SetQueryID("set a resource-query Id")
    resourceQueryRecord, response, err := schematicsService.GetResourcesQuery(getResourcesQueryOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(resourceQueryRecord, "", "  ")
    fmt.Println(string(b))
    fmt.Println(response)
    

Response

Describe resource query record

Status Code

  • Successfully fetches a resources query 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 was not found

  • 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": "workspace_resource",
      "name": "hello",
      "id": "default.RESOURCEQUERY.hello.101010",
      "created_at": "2021-04-09T10:20:06.572Z",
      "created_by": "user@ibm.com",
      "updated_at": "1901-01-01T00:00:00.000Z",
      "queries": [
        {
          "query_type": "workspaces",
          "query_condition": [
            {
              "name": "workspace-id",
              "value": "us-east.ACTION.kubectlWorkshop.101010",
              "description": "string"
            },
            {
              "name": "resource-name",
              "value": "tf1234vpc-pubpriv-frontend-vsi",
              "description": "string"
            }
          ]
        }
      ]
    }

Update resources query definition

Use this API to update the resource query definition used to build the dynamic inventory for the Schematics Action. For more information, about resource query commands, refer to ibmcloud schematics resource query update. Note you cannot update the location and region, resource group once a resource query 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.

PUT /v2/resources_query/{query_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

  • Resource query Id. Use GET /v2/resource_query API to look up the Resource query definition Ids in your IBM Cloud account.

Replace the resources query definition

  • curl --location --request PUT https://schematics.cloud.ibm.comv2/resources_query/default.RESOURCEQUERY.hello.2fdda8ce --header "Authorization:<access_token> " --header "Content-Type: application/json" --header "Cookie: " --data-raw "{ "type": "workspace_resource","name": "hello my world","queries": [{"query_type": "workspaces","query_condition": [{"name": "workspace-id","value": "us-east.ACTION.kubectlWorkshop.41901417","description": "string"},{"name": "resource-name","value": "tf00vpc-pubpriv-frontend-vsi","description": "string"}]}]}
  • resource_query_record = schematics_service.replace_resources_query(
    query_id= "set a query Id",
    type= "workspace_resource",
    name= "hello my world",
    queries= [
    {
    query_type: "workspaces",
    query_condition: [
    {
    name: "workspace-id",
    value: "us-east.ACTION.kubectlWorkshop.41901417",
    description: "string"
    },
    {
    name: "resource-name",
    value: "tf00vpc-pubpriv-frontend-vsi",
    description: "string"
    }
    ]}]
    ).get_result()
    print(json.dumps(resource_query_record, indent=2))
    ]}]}
    
  • ReplaceResourcesQueryOptions replaceResourcesQueryOptions = new ReplaceResourcesQueryOptions.Builder()
    .queryId("set a query Id")
    .type("workspace_resource")
    .name("hello my world this is resource_query")
    .build();
    Response<ResourceQueryRecord> response = service.replaceResourcesQuery(replaceResourcesQueryOptions).execute();
    ResourceQueryRecord resourceQueryRecord = response.getResult();
    System.out.println(resourceQueryRecord);
    
  • const params = {
    queryId: 'set query Id',
    type: "workspace_resource",
    name: "hello my world updated changes",
    };
    schematicsService.replaceResourcesQuery(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
    
  • replaceResourcesQueryOptions := schematicsService.NewReplaceResourcesQueryOptions(
    testString)
    replaceResourcesQueryOptions.SetQueryID("default.RESOURCEQUERY.demorqcli.79f53cb8")
    replaceResourcesQueryOptions.SetType("workspace_resource")replaceResourcesQueryOptions.SetName("hello my world short description")
    resourceQueryRecord, response, err := schematicsService.ReplaceResourcesQuery(replaceResourcesQueryOptions)
    if err != nil {
    panic(err)
    }
    b, _ := json.MarshalIndent(resourceQueryRecord, "", "  ")
    fmt.Println(string(b))
    fmt.Println(response)
    

Response

Describe resource query record

Status Code

  • Successfully updated the resources query 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 is locked, cannot be updated or deleted

  • 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": "workspace_resource",
      "name": "hello my world",
      "id": "default.RESOURCEQUERY.hello.10101",
      "created_at": "2021-04-09T10:20:06.572Z",
      "created_by": "user@ibm.com",
      "updated_at": "2021-04-09T10:34:39.243Z",
      "updated_by": "user@ibm.com",
      "queries": [
        {
          "query_type": "workspaces",
          "query_condition": [
            {
              "name": "workspace-id",
              "value": "us-east.ACTION.kubectlWorkshop.12317",
              "description": "string"
            },
            {
              "name": "resource-name",
              "value": "tf12312vpc-pubpriv-frontend-vsi",
              "description": "string"
            }
          ]
        }
      ]
    }

Run the resource query

Run the resource query

POST /v2/resources_query/{query_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

  • Resource query Id. Use GET /v2/resource_query API to look up the Resource query definition Ids in your IBM Cloud account.

Response

Describe resource query

Status Code

  • Successfully executed resource query

  • 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

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

Delete resources query

Use this API to delete the resource query definition by Id. For more information, about resource query commands, refer to ibmcloud schematics resource query delete.

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/resources_query/{query_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.

  • Equivalent to -force options in the command line

  • Auto propagate the chaange or deletion to the dependent resources

Path Parameters

  • Resource query Id. Use GET /v2/resource_query API to look up the Resource query definition Ids in your IBM Cloud account.

  • curl --location --request DELETE https://schematics.cloud.ibm.com/v2/resources_query/default.RESOURCEQUERY.samplequerytest.699fd513 --header 'Authorization: ' --header "Content-Type: application/json" --header "Cookie: " --data-raw "
  • response = schematics_service.delete_resources_query(
    query_id='set query id'
    ).get_result()
    print(json.dumps(response, indent=2))
    
  • DeleteResourcesQueryOptions deleteResourcesQueryOptions = new DeleteResourcesQueryOptions.Builder()
    .queryId("set a query Id")
    .build();
    service.deleteResourcesQuery(deleteResourcesQueryOptions).execute();
    
  • const params = {
    queryId: 'set query id',
    };
    schematicsService.deleteResourcesQuery(params)
    .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
    })
    .catch(err => {
    console.warn(err)
    });
    
  • deleteResourcesQueryOptions := schematicsService.NewDeleteResourcesQueryOptions(
    testString)
    deleteResourcesQueryOptions.SetQueryID("set query id")
    response, err := schematicsService.DeleteResourcesQuery(deleteResourcesQueryOptions)
    if err != nil {
    panic(err)
    }
    fmt.Println(response)
    

Response

Status Code

  • Successfully deletes a resources query 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.

  • The specified resource was not found

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

  • 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 all registered/unregistered agents in the Account

Get all registered or unregistered agents, in the 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 /v2/settings/agents

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

  • Level of details returned by the get method

    Allowable values: [summary,detailed,ids]

  • Use new to get all unregistered agents; use saved to get all registered agents.

    Allowable values: [all,new,saved]

Response

The list of agent details.

Status Code

  • Successfully listed all agent in the account

  • 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": 2,
      "limit": 100,
      "offset": 0,
      "agents": [
        {
          "name": "smulampaka-agent9",
          "description": "Register agent",
          "resource_group": "Default",
          "tags": [
            "agent"
          ],
          "agent_location": "us-south",
          "location": "eu-de",
          "agent_crn": "crn:v1:staging:public:schematics:eu-de:a/0ddd18d6a00f4e8ea3fb582446c5375c:a39aa93c-4ee1-4219-b4c5-afd75940370a:agent:smulampaka-agent9.deA.01a3",
          "id": "smulampaka-agent9.deA.01a3",
          "registered_at": "2022-07-07T05:32:24.007Z",
          "registered_by": "schematics@ibm.com",
          "updated_at": "1901-01-01T00:00:00.000Z",
          "user_state": {
            "state": "enable",
            "set_by": "schematics@ibm.com",
            "set_at": "2022-07-07T05:32:24.007Z"
          },
          "connection_state": {
            "state": "Connected",
            "checked_at": "2022-07-07T05:32:24.007Z"
          },
          "system_state": {}
        },
        {
          "name": "devagentapi",
          "description": "Register agent description change",
          "resource_group": "Default",
          "tags": [
            "agent"
          ],
          "agent_location": "us-south",
          "location": "eu-de",
          "agent_crn": "crn:v1:staging:public:schematics:eu-de:a/0ddd18d6a00f4e8ea3fb582446c5375c:a39aa93c-4ee1-4219-b4c5-afd75940370a:agent:devagentapi.deA.03a4",
          "id": "devagentapi.deA.03a4",
          "registered_at": "2022-07-07T05:38:06.814Z",
          "registered_by": "schematics@ibm.com",
          "updated_at": "2022-07-07T05:38:56.389Z",
          "updated_by": "schematics@ibm.com",
          "user_state": {
            "state": "enable",
            "set_by": "schematics@ibm.com",
            "set_at": "2022-07-07T05:38:06.814Z"
          },
          "connection_state": {
            "state": "Connected",
            "checked_at": "2022-07-07T05:38:06.814Z"
          },
          "system_state": {}
        }
      ]
    }

Register the agent with schematics

Register the agent with schematics

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/settings/agents

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.

Register the agent with schematics.

  • curl --cart --request POST http://schematics.cloud.ibm.com/v2/settings/agents  "Authorization: <access_token>" --header "enable_blueprint: true" "Content-Type: application/json" "Github-token: github_token" -d "{"name": "devagentapi","description": "Register agent","resource_group": "Default", "tags": ["agent"],"location": "eu-de","agent_location": "us-south","profile_id": "smkumar9","user_state": {"state": "enable"}}"

Response

The agent registration details, with user inputs and system generated data.

Status Code

  • Successfully Registered the agent

  • 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

  • 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": "devagentapi",
      "description": "Register agent",
      "resource_group": "5dcf6a39526247fa9cd1ff97a58b7dda",
      "tags": [
        "agent"
      ],
      "agent_location": "us-south",
      "location": "eu-de",
      "profile_id": "smkumar9",
      "agent_crn": "crn:v1:staging:public:schematics:eu-de:a/0ddd18d6a00f4e8ea3fb582446c5375c:a39aa93c-4ee1-4219-b4c5-afd75940370a:agent:devagentapi.deA.03a4",
      "id": "devagentapi.deA.03a4",
      "registered_at": "2022-07-07T05:38:06.814Z",
      "registered_by": "schematics@ibm.com",
      "updated_at": "1901-01-01T00:00:00.000Z",
      "user_state": {
        "state": "enable",
        "set_by": "schematics@ibm.com",
        "set_at": "2022-07-07T05:38:06.814Z"
      },
      "connection_state": {
        "state": "Connected",
        "checked_at": "2022-07-07T05:38:06.814Z"
      },
      "system_state": {}
    }

Get the registered agent details

Reterive list the registered agent details

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/settings/agents/{agent_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

  • Agent ID to get the details of agent

Query Parameters

  • Level of details returned by the get method

    Allowable values: [summary,detailed,ids]

  • curl --request GET http://schematics.cloud.ibm.com/v2/settings/agents/{agent_id} --header "Authorization: <access_token>" 'X-Feature-Agents: true' "refresh_token: <refresh-token>"

Response

The agent registration details, with user inputs and system generated data.

Status Code

  • Successfully got the agent details

  • 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 was not found

  • 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": "agent-beta1-testing",
      "description": "Create Agent",
      "resource_group": "schematics-prod",
      "tags": [
        "env:prod",
        "mytest"
      ],
      "version": "v1.0.0",
      "schematics_location": "us-south",
      "agent_location": "us-south",
      "user_state": {
        "state": "enable",
        "set_by": "schematics@in.ibm.com",
        "set_at": "2023-03-16T06:12:13.684Z"
      },
      "agent_crn": "crn:v1:bluemix:public:schematics:us-south:a/<crn>:agent:agent-beta1-testing.soA.748e",
      "created_at": "2023-03-16T06:12:13.684Z",
      "creation_by": "schematics@in.ibm.com",
      "updated_at": "1901-01-01T00:00:00.000Z",
      "system_state": {
        "status_code": "draft"
      },
      "agent_kpi": {
        "availability_indicator": "normal",
        "lifecycle_indicator": "consistent",
        "percent_usage_indicator": "30%"
      }
    }

Deregister the agent

Deregistering an agent.

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/settings/agents/{agent_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

  • Agent ID to get the details of agent

    Response

    Status Code

    • Successfully deregistered the agent

    • 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 was not found

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

    Update the agent registration

    Update the agent registeration.

    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/settings/agents/{agent_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

    • Agent ID to get the details of agent

    Update the agent registration.

    • curl --cart --request PATCH http://schematics.cloud.ibm.com/v2/settings/agents/{agent_id} "Authorization: <access_token>" --header "enable_blueprint: true" "Content-Type: application/json" "Github-token: github_token" -d "{"name": "devagentapi","description": "Register agent description change","resource_group": "Default", "tags": ["agent"],"location": "eu-de","agent_location": "us-south","profile_id": "smkumar9","user_state": {"state": "enable"}}"

    Response

    The agent registration details, with user inputs and system generated data.

    Status Code

    • Successfully Registered the agent

    • 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

    • 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": "devagentapi",
        "description": "Register agent description change",
        "resource_group": "5dcf6a39526247fa9cd1ff97a58b7dda",
        "tags": [
          "agent"
        ],
        "agent_location": "us-south",
        "location": "eu-de",
        "profile_id": "smkumar9",
        "agent_crn": "crn:v1:staging:public:schematics:eu-de:a/0ddd18d6a00f4e8ea3fb582446c5375c:a39aa93c-4ee1-4219-b4c5-afd75940370a:agent:devagentapi.deA.03a4",
        "id": "devagentapi.deA.03a4",
        "registered_at": "2022-07-07T05:38:06.814Z",
        "registered_by": "schematics@ibm.com",
        "updated_at": "2022-07-07T05:38:56.389Z",
        "updated_by": "schematics@ibm.com",
        "user_state": {
          "state": "enable",
          "set_by": "schematics@ibm.com",
          "set_at": "2022-07-07T05:38:06.814Z"
        },
        "connection_state": {
          "state": "Connected",
          "checked_at": "2022-07-07T05:38:06.814Z"
        },
        "system_state": {}
      }

    List agents

    Retrieve a list of Schematics agents from your IBM Cloud account that you have access to. The list of agents 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 agents that are created in us-south or us-east` are returned. For more information about frequently asked questions, see FAQ and Troubleshooting guide. For more information about supported API endpoints, see API endpoint.

    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/agents

    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

    • Level of details returned by the get method

      Allowable values: [summary,detailed,ids]

    • Use new to get all unregistered agents; use saved to get all registered agents.

      Allowable values: [all,new,saved]

    • curl https://schematics.cloud.ibm.com/v2/agents   -H 'Authorization: Bearer <Auth Key>'   -H 'X-Feature-Agents: true'   -H 'refresh_token: <refresh_token>'
    • ListAgentDataOptions listAgentDataOptions = new ListAgentDataOptions.Builder().xFeatureAgents(true)
      .build();
      
      Response<AgentDataList> response = service.listAgentData(listAgentDataOptions).execute();
      
      AgentDataList agentList = response.getResult();
      System.out.println(agentList);                    
      
    • response = schematics_service.list_agent_data()
      agent_list = response.get_result()
      
      print(json.dumps(agent_list, indent=2))
      
    • const params = {xFeatureAgents: true,
      };
      schematicsService
      .listAgentData(params)
      .then(response => {
      console.log(response.result);
      })
      .catch(err => {
      console.warn(err);
      });
      
    • result, detailedResponse, err := 
      schematicsService.ListAgentData(&schematicsv1.ListAgentDataOptions
      {
      XFeatureAgents: core.BoolPtr(true),
      })
      if err != nil {
      fmt.Printf("Failed to list the agent data : %v and the response is %s", err, detailedResponse)
      }
      
      w, err := json.Marshal(result)
      fmt.Print("Agents:", string(w))
      

    Response

    The list of agents.

    Status Code

    • Successfully listed all agents in the account

    • 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": 2,
        "limit": 100,
        "offset": 0,
        "agents": [
          {
            "name": "smulampaka-agent9",
            "description": "Register agent",
            "resource_group": "Default",
            "tags": [
              "agent"
            ],
            "agent_location": "us-south",
            "location": "eu-de",
            "agent_crn": "crn:v1:staging:public:schematics:eu-de:a/0ddd18d6a00f4e8ea3fb582446c5375c:a39aa93c-4ee1-4219-b4c5-afd75940370a:agent:smulampaka-agent9.deA.01a3",
            "id": "smulampaka-agent9.deA.01a3",
            "registered_at": "2022-07-07T05:32:24.007Z",
            "registered_by": "schematics@ibm.com",
            "updated_at": "1901-01-01T00:00:00.000Z",
            "user_state": {
              "state": "enable",
              "set_by": "schematics@ibm.com",
              "set_at": "2022-07-07T05:32:24.007Z"
            },
            "connection_state": {
              "state": "Connected",
              "checked_at": "2022-07-07T05:32:24.007Z"
            },
            "system_state": {}
          },
          {
            "name": "devagentapi",
            "description": "Register agent description change",
            "resource_group": "Default",
            "tags": [
              "agent"
            ],
            "agent_location": "us-south",
            "location": "eu-de",
            "agent_crn": "crn:v1:staging:public:schematics:eu-de:a/0ddd18d6a00f4e8ea3fb582446c5375c:a39aa93c-4ee1-4219-b4c5-afd75940370a:agent:devagentapi.deA.03a4",
            "id": "devagentapi.deA.03a4",
            "registered_at": "2022-07-07T05:38:06.814Z",
            "registered_by": "schematics@ibm.com",
            "updated_at": "2022-07-07T05:38:56.389Z",
            "updated_by": "schematics@ibm.com",
            "user_state": {
              "state": "enable",
              "set_by": "schematics@ibm.com",
              "set_at": "2022-07-07T05:38:06.814Z"
            },
            "connection_state": {
              "state": "Connected",
              "checked_at": "2022-07-07T05:38:06.814Z"
            },
            "system_state": {}
          }
        ]
      }

    Create an agent

    Subsequently, create an agent definition to manage the agent deployment with the agent configuration that will be used to deploy your agent to its target location. Getting API endpoint:-

    • The Schematics API endpoint that you use to create the agent determines where your Schematics agent run and your data is stored. For more information about supported API endpoints, see API endpoints. * 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 agent 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. * Follow the steps to retrieve your IAM access token and authenticate with IBM Cloud Schematics by using the API. * For more information about frequently asked questions, see FAQ and Troubleshooting guide.

      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/agents

    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.

    Create the agent using schematics.

    • curl -X POST https://schematics.cloud.ibm.com/v2/agents \-H 'Authorization: Bearer <Auth Key>' -H 'X-Feature-Agents: true' -H 'refresh_token: <refresh_token> ' -d '{
      "name": "AgentName",
      "description": "Create Agent",
      "resource_group": "Default",
      "tags": [
      "tag1",
      "tag2"
      ],
      "version": "v1.0.0",
      "schematics_location": "us-south",
      "agent_location": "us-south",
      "agent_infrastructure": {
      "infra_type": "ibm_kubernetes",
      "cluster_id": "cluster_id",
      "cluster_resource_group": "Default",
      "cos_instance_name": "blueprint_basic",
      "cos_bucket_name": "sample_bucket_name",
      "cos_bucket_region": "us-east"
      },
      "agent_inputs": [
      {
      "name": "ibmcloud_api_key",
      "value": "<api_key of the account where cluster and cos are present>",
      "metadata": {
      "secure": true
      }
      },
      {
      "name": "ansible_pull_ibmcloud_api_key",
      "value": "jenkins api_key for pulling agents images",
      "metadata": {
      "secure": true
      }
      },
      {   
      "name": "devops_api_key",
      "value": "api_key where you want to create agent and run fvts",
      "metadata": {
      "secure": true
      }
      }
      ],
      "user_state": {
      "state": "enable"
      }
      }'
      
    • AgentInfrastructure agentInfrastructureModel = new AgentInfrastructure.Builder().infraType("ibm_kubernetes")
      .clusterId("testString")
      .clusterResourceGroup("testString")
      .cosInstanceName("testString")
      .cosBucketName("testString")
      .cosBucketRegion("testString")
      .build();
      
      
      AgentMetadataInfo agentMetadataInfoModel = new AgentMetadataInfo.Builder()
      .name("purpose")
      .value(java.util.Arrays.asList("git", "terraform", "ansible"))
      .build();
      
      
      VariableMetadata variableMetadataModel = new VariableMetadata.Builder()
      .type("boolean")
      .aliases(java.util.Arrays.asList("testString"))
      .description("testString")
      .cloudDataType("testString")
      .defaultValue("testString")
      .linkStatus("normal")
      .secure(true)
      .immutable(true)
      .hidden(true)
      .required(true)
      .options(java.util.Arrays.asList("testString"))
      .minValue(Long.valueOf("26"))
      .maxValue(Long.valueOf("26"))
      .minLength(Long.valueOf("26"))
      .maxLength(Long.valueOf("26"))
      .matches("testString")
      .position(Long.valueOf("26"))
      .groupBy("testString")
      .source("testString")
      .build();
      
      
      VariableData variableDataModel = new VariableData.Builder()
      .name("testString")
      .value("testString")
      .useDefault(true)
      .metadata(variableMetadataModel)
      .build();
      
      
      AgentUserState agentUserStateModel = new AgentUserState.Builder()
      .state("enable")
      .build();
      
      
      AgentKPIData agentKpiDataModel = new AgentKPIData.Builder()
      .availabilityIndicator("available")
      .lifecycleIndicator("consistent")
      .percentUsageIndicator("testString")
      .applicationIndicators(java.util.Arrays.asList("testString"))
      .infraIndicators(java.util.Arrays.asList("testString"))
      .build();
      
      
      CreateAgentDataOptions createAgentDataOptionsModel = new CreateAgentDataOptions.Builder()
      .xFeatureAgents(true)
      .name("AgentFromJavaSDK")
      .resourceGroup("Default")
      .version("v1.0.0")
      .schematicsLocation("us-south")
      .agentLocation("us-south")
      .agentInfrastructure(agentInfrastructureModel)
      .description("Create Agent")
      .tags(java.util.Arrays.asList("testString"))
      .agentMetadata(java.util.Arrays.asList(agentMetadataInfoModel))
      .agentInputs(java.util.Arrays.asList(variableDataModel))
      .userState(agentUserStateModel)
      .agentKpi(agentKpiDataModel)
      .build();
      
      Response<AgentData> response = service.createAgentData(createAgentDataOptionsModel).execute();
      
      AgentData agentCreate = response.getResult();
      System.out.println(agentCreate);                   
      
    • agent_infrastructure_model = {'infra_type': 'ibm_kubernetes',
      'cluster_id': 'blrpsgow026e2vt98t0g',
      'cluster_resource_group': 'Default',
      'cos_instance_name': 'agent-dev-cos',
      'cos_bucket_name': 'agent-dev-cos-bucket',
      'cos_bucket_region': 'us-south',
      }
      
      agent_metadata_info_model = {
      'name': 'purpose',
      'value': ['git'],
      }
      
      variable_metadata_model = {
      'type': 'boolean',
      'aliases': ['testString'],
      'description': 'testString',
      'cloud_data_type': 'testString',
      'default_value': 'testString',
      'link_status': 'normal',
      'secure': True,
      'immutable': True,
      'hidden': True,
      'required': True,
      'options': ['testString'],
      'min_value': 38,
      'max_value': 38,
      'min_length': 38,
      'max_length': 38,
      'matches': 'testString',
      'position': 38,
      'group_by': 'testString',
      'source': 'testString',
      }
      
      variable_data_model = {
      'name': 'ibmcloud_api_key',
      'value': 'Uqd6nEZEkLRp2VP30H2o-b5b6qcdevpY3w9_g3hs31L5',
      'use_default': True,
      'metadata': variable_metadata_model,
      }
      
      agent_user_state_model = {
      'state': 'enable',
      }
      
      agent_kpi_data_model = {
      'availability_indicator': 'available',
      'lifecycle_indicator': 'consistent',
      'percent_usage_indicator': 'testString',
      'application_indicators': ['testString'],
      'infra_indicators': ['testString'],
      }
      
      response = schematics_service.create_agent_data(
      name='MyDevAgent',
      resource_group='Default',
      version='v1.0.0',
      schematics_location='us-south',
      agent_location='us-south',
      agent_infrastructure=agent_infrastructure_model,
      description='Create Agent',
      tags=['env:test','mytest'],
      agent_metadata=[agent_metadata_info_model],
      agent_inputs=[variable_data_model],
      user_state=agent_user_state_model,
      agent_kpi=agent_kpi_data_model,
      )
      
      agent_data = response.get_result()
      print(json.dumps(agent_data, indent=2))
      
    • const agentInfrastructureModel = {
      infra_type: 'ibm_kubernetes',
      cluster_id: 'testString',
      cluster_resource_group: 'testString',
      cos_instance_name: 'testString',
      cos_bucket_name: 'testString',
      cos_bucket_region: 'testString',
      };
      
      const agentMetadataInfoModel = {
      name: 'purpose',
      value: ['git', 'terraform', 'ansible'],
      };
      
      const variableMetadataModel = {
      type: 'boolean',
      aliases: ['testString'],
      description: 'testString',
      cloud_data_type: 'testString',
      default_value: 'testString',
      link_status: 'normal',
      secure: true,
      immutable: true,
      hidden: true,
      required: true,
      options: ['testString'],
      min_value: 38,
      max_value: 38,
      min_length: 38,
      max_length: 38,
      matches: 'testString',
      position: 38,
      group_by: 'testString',
      source: 'testString',
      };
      
      const variableDataModel = {
      name: 'testString',
      value: 'testString',
      use_default: true,
      metadata: variableMetadataModel,
      };
      
      const agentUserStateModel = {
      state: 'enable',
      };
      
      const agentKpiDataModel = {
      availability_indicator: 'available',
      lifecycle_indicator: 'consistent',
      percent_usage_indicator: 'testString',
      application_indicators: ['testString'],
      infra_indicators: ['testString'],
      };
      
      const params = {
      name: 'AgentFromNode',
      resourceGroup: 'Default',
      version: 'v1.0.0',
      schematicsLocation: 'us-south',
      agentLocation: 'us-south',
      agentInfrastructure: agentInfrastructureModel,
      description: 'Create Agent',
      tags: ['testString'],
      agentMetadata: [agentMetadataInfoModel],
      agentInputs: [variableDataModel],
      userState: agentUserStateModel,
      agentKpi: agentKpiDataModel,
      xFeatureAgents: true,
      };
      
      schematicsService
      .createAgentData(params)
      .then(response => {
      console.log(response.result);
      })
      .catch(err => {
      console.warn(err);
      });
      
    • agentInfrastructureModel := new(schematicsv1.AgentInfrastructure) agentInfrastructureModel.InfraType = core.StringPtr("ibm_kubernetes")
      agentInfrastructureModel.ClusterID = core.StringPtr("testString")
      agentInfrastructureModel.ClusterResourceGroup = core.StringPtr("testString")
      agentInfrastructureModel.CosInstanceName = core.StringPtr("testString")
      agentInfrastructureModel.CosBucketName = core.StringPtr("testString")
      agentInfrastructureModel.CosBucketRegion = core.StringPtr("testString")
      
      agentMetadataInfoModel := new(schematicsv1.AgentMetadataInfo)
      agentMetadataInfoModel.Name = core.StringPtr("purpose")
      agentMetadataInfoModel.Value = []string{"git", "terraform", "ansible"}
      
      variableMetadataModel := new(schematicsv1.VariableMetadata)
      variableMetadataModel.Type = core.StringPtr("boolean")
      variableMetadataModel.Aliases = []string{"testString"}
      variableMetadataModel.Description = core.StringPtr("testString")
      variableMetadataModel.CloudDataType = core.StringPtr("testString")
      variableMetadataModel.DefaultValue = core.StringPtr("testString")
      variableMetadataModel.LinkStatus = core.StringPtr("normal")
      variableMetadataModel.Secure = core.BoolPtr(true)
      variableMetadataModel.Immutable = core.BoolPtr(true)
      variableMetadataModel.Hidden = core.BoolPtr(true)
      variableMetadataModel.Required = core.BoolPtr(true)
      variableMetadataModel.Options = []string{"testString"}
      variableMetadataModel.MinValue = core.Int64Ptr(int64(38))
      variableMetadataModel.MaxValue = core.Int64Ptr(int64(38))
      variableMetadataModel.MinLength = core.Int64Ptr(int64(38))
      variableMetadataModel.MaxLength = core.Int64Ptr(int64(38))
      variableMetadataModel.Matches = core.StringPtr("testString")
      variableMetadataModel.Position = core.Int64Ptr(int64(38))
      variableMetadataModel.GroupBy = core.StringPtr("testString")
      variableMetadataModel.Source = core.StringPtr("testString")
      
      variableDataModel := new(schematicsv1.VariableData)
      variableDataModel.Name = core.StringPtr("testString")
      variableDataModel.Value = core.StringPtr("testString")
      variableDataModel.UseDefault = core.BoolPtr(true)
      variableDataModel.Metadata = variableMetadataModel
      
      agentUserStateModel := new(schematicsv1.AgentUserState)
      agentUserStateModel.State = core.StringPtr("enable")
      
      agentKpiDataModel := new(schematicsv1.AgentKPIData)
      agentKpiDataModel.AvailabilityIndicator = core.StringPtr("available")
      agentKpiDataModel.LifecycleIndicator = core.StringPtr("consistent")
      agentKpiDataModel.PercentUsageIndicator = core.StringPtr("testString")
      agentKpiDataModel.ApplicationIndicators = []interface{}{"testString"}
      agentKpiDataModel.InfraIndicators = []interface{}{"testString"}
      
      result, detailedResponse, err := schematicsService.CreateAgentData(&schematicsv1.CreateAgentDataOptions{
      XFeatureAgents:      core.BoolPtr(true),
      Name:                core.StringPtr("MyDevAgentNithin"),
      ResourceGroup:       core.StringPtr("Default"),
      Version:             core.StringPtr("v1.0.0"),
      SchematicsLocation:  core.StringPtr("us-south"),
      AgentLocation:       core.StringPtr("us-south"),
      AgentInfrastructure: agentInfrastructureModel,
      Description:         core.StringPtr("Create Agent"),
      Tags:                []string{"testString"},
      AgentMetadata:       []schematicsv1.AgentMetadataInfo{*agentMetadataInfoModel},
      AgentInputs:         []schematicsv1.VariableData{*variableDataModel},
      UserState:           agentUserStateModel,
      AgentKpi:            agentKpiDataModel,
      })
      if err != nil {
      fmt.Printf("Failed to create the agent : %v and the response is %s", err, detailedResponse)
      }
      
      w, err := json.Marshal(result)
      fmt.Print("Agents:", string(w)))
      

    Response

    The agent details, with user inputs and system generated data.

    Status Code

    • Successfully created the agent

    • 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

    • 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": "agent-beta1-testing",
        "description": "Create Agent",
        "resource_group": "ba8818923fe846e6a8fb5c6d72075768",
        "tags": [
          "env:prod",
          "mytest"
        ],
        "version": "v1.0.0",
        "schematics_location": "us-south",
        "agent_location": "us-south",
        "user_state": {
          "state": "enable",
          "set_by": "test@in.ibm.com",
          "set_at": "2023-03-16T06:12:13.684Z"
        },
        "agent_crn": "crn:v1:bluemix:public:schematics:us-south:a/<crn_value>:agent:agent-beta1-testing.soA.748e",
        "id": "agent-beta1-testing.soA.748e",
        "created_at": "2023-03-16T06:12:13.684Z",
        "creation_by": "test@in.ibm.com",
        "updated_at": "1901-01-01T00:00:00.000Z",
        "system_state": {
          "status_code": "draft"
        }
      }

    Get agent details

    Retrieve a detailed configuration of an agent with a specific agent ID. The agent 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 agents that are created in us-south or us-east` are returned. For more information about frequently asked questions, see FAQ and Troubleshooting guide. For more information about supported API endpoints, see API endpoint.

    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/agents/{agent_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

    • Agent ID to get the details of agent

    Query Parameters

    • Level of details returned by the get method

      Allowable values: [summary,detailed,ids]

    • curl https://schematics.cloud.ibm.com/v2/agents/<agent_id>   -H 'Authorization: Bearer <ApiKey>'   -H 'X-Feature-Agents: true'   -H 'refresh_token: <refresh token>'
    • GetAgentDataOptions getAgentDataOptions = new GetAgentDataOptions.Builder().xFeatureAgents(true)
      .agentId("<agent_id>")
      .build();
      
      Response<AgentData> response = service.getAgentData(getAgentDataOptions).execute();
      
      AgentData agentList = response.getResult();
      System.out.println(agentList);                   
      
    • response =  schematics_service.get_agent_data("<agent_id>")agent_list = response.get_result()
      
      print(json.dumps(agent_list, indent=2)) 
      
    • const params = {xFeatureAgents: true,
      agentId: "MyDevAgentNithinNew.soA.f2ed",
      };
      
      schematicsService
      .getAgentData(params)
      .then(response => {
      console.log(response.result);
      })
      .catch(err => {
      console.warn(err);
      });
      
    • result, detailedResponse, err :=  schematicsService.GetAgentData(&schematicsv1.GetAgentDataOptions{XFeatureAgents: core.BoolPtr(true),
      AgentID:        core.StringPtr("<agent_id>"),
      })
      if err != nil {
      fmt.Printf("Failed to get the agent data : %v and the response is %s", err, detailedResponse)
      }
      
      w, err := json.Marshal(result)
      fmt.Print("Agents:", string(w))
       
      

    Response

    The agent details, with user inputs and system generated data.

    Status Code

    • Successfully got the agent details

    • 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 was not found

    • 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": "agent-beta1-testing",
        "description": "Create Agent",
        "resource_group": "schematics-prod",
        "tags": [
          "env:prod",
          "mytest"
        ],
        "version": "v1.0.0",
        "schematics_location": "us-south",
        "agent_location": "us-south",
        "user_state": {
          "state": "enable",
          "set_by": "schematics@in.ibm.com",
          "set_at": "2023-03-16T06:12:13.684Z"
        },
        "agent_crn": "crn:v1:bluemix:public:schematics:us-south:a/<crn>:agent:agent-beta1-testing.soA.748e",
        "created_at": "2023-03-16T06:12:13.684Z",
        "creation_by": "schematics@in.ibm.com",
        "updated_at": "1901-01-01T00:00:00.000Z",
        "system_state": {
          "status_code": "draft"
        },
        "agent_kpi": {
          "availability_indicator": "normal",
          "lifecycle_indicator": "consistent",
          "percent_usage_indicator": "30%"
        }
      }

    Update agent

    Use update agent API to update or replace the entire agent. For more information about steps to apply UPDATE and PUT command, see Deploying agent. For more information about supported API endpoints, see API endpoint.

    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 /v2/agents/{agent_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.

    • This IAM token is required only when trying to update an agent from one version to other.

      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

    • Agent ID to get the details of agent

    Update the agent registration.

    • curl -X PUT https://schematics.cloud.ibm.com/v2/agents/{agent_id} \-H 'Authorization: Bearer <Auth Key>' -H 'X-Feature-Agents: true' -H 'refresh_token: <refresh_token> ' -d '{
      "name": "AgentName",
      "description": "New Description",
      "resource_group": "Default",
      "tags": [
      "tag1",
      "tag2"
      ],
      "version": "v1.0.0",
      "schematics_location": "us-south",
      "agent_location": "us-south",
      "agent_infrastructure": {
      "infra_type": "ibm_kubernetes",
      "cluster_id": "cluster_id",
      "cluster_resource_group": "Default",
      "cos_instance_name": "blueprint_basic",
      "cos_bucket_name": "sample_bucket_name",
      "cos_bucket_region": "us-east"
      },
      "agent_inputs": [
      {
      "name": "ibmcloud_api_key",
      "value": "<api_key of the account where cluster and cos are present>",
      "metadata": {
      "secure": true
      }
      },
      {
      "name": "ansible_pull_ibmcloud_api_key",
      "value": "jenkins api_key for pulling agents images",
      "metadata": {
      "secure": true
      }
      },
      {   
      "name": "devops_api_key",
      "value": "api_key where you want to create agent and run fvts",
      "metadata": {
      "secure": true
      }
      }
      ],
      "user_state": {
      "state": "enable"
      }
      }'
      
    • AgentInfrastructure agentInfrastructureModel = new AgentInfrastructure.Builder().infraType("ibm_kubernetes")
      .clusterId("testString")
      .clusterResourceGroup("testString")
      .cosInstanceName("testString")
      .cosBucketName("testString")
      .cosBucketRegion("testString")
      .build();
      
      
      AgentMetadataInfo agentMetadataInfoModel = new AgentMetadataInfo.Builder()
      .name("purpose")
      .value(java.util.Arrays.asList("git", "terraform", "ansible"))
      .build();
      
      
      VariableMetadata variableMetadataModel = new VariableMetadata.Builder()
      .type("boolean")
      .aliases(java.util.Arrays.asList("testString"))
      .description("testString")
      .cloudDataType("testString")
      .defaultValue("testString")
      .linkStatus("normal")
      .secure(true)
      .immutable(true)
      .hidden(true)
      .required(true)
      .options(java.util.Arrays.asList("testString"))
      .minValue(Long.valueOf("26"))
      .maxValue(Long.valueOf("26"))
      .minLength(Long.valueOf("26"))
      .maxLength(Long.valueOf("26"))
      .matches("testString")
      .position(Long.valueOf("26"))
      .groupBy("testString")
      .source("testString")
      .build();
      
      
      VariableData variableDataModel = new VariableData.Builder()
      .name("testString")
      .value("testString")
      .useDefault(true)
      .metadata(variableMetadataModel)
      .build();
      
      
      AgentUserState agentUserStateModel = new AgentUserState.Builder()
      .state("enable")
      .build();
      
      
      AgentKPIData agentKpiDataModel = new AgentKPIData.Builder()
      .availabilityIndicator("available")
      .lifecycleIndicator("consistent")
      .percentUsageIndicator("testString")
      .applicationIndicators(java.util.Arrays.asList("testString"))
      .infraIndicators(java.util.Arrays.asList("testString"))
      .build();
      
      
      CreateAgentDataOptions createAgentDataOptionsModel = new CreateAgentDataOptions.Builder()
      .xFeatureAgents(true)
      .agentId("<agent_id>")  
      .name("AgentFromJavaSDK")
      .resourceGroup("Default")
      .version("v1.0.0")
      .schematicsLocation("us-south")
      .agentLocation("us-south")
      .agentInfrastructure(agentInfrastructureModel)
      .description("New Description")
      .tags(java.util.Arrays.asList("testString"))
      .agentMetadata(java.util.Arrays.asList(agentMetadataInfoModel))
      .agentInputs(java.util.Arrays.asList(variableDataModel))
      .userState(agentUserStateModel)
      .agentKpi(agentKpiDataModel)
      .build();
      
      Response<AgentData> response = service.updateAgentData(updateAgentDataOptionsModel).execute();
      
      AgentData agentUpdate = response.getResult();
      System.out.println(agentUpdate);                     
      
    • agent_infrastructure_model = {'infra_type': 'ibm_kubernetes',
      'cluster_id': 'blrpsgow026e2vt98t0g',
      'cluster_resource_group': 'Default',
      'cos_instance_name': 'agent-dev-cos',
      'cos_bucket_name': 'agent-dev-cos-bucket',
      'cos_bucket_region': 'us-south',
      }
      
      agent_metadata_info_model = {
      'name': 'purpose',
      'value': ['git'],
      }
      
      variable_metadata_model = {
      'type': 'boolean',
      'aliases': ['testString'],
      'description': 'testString',
      'cloud_data_type': 'testString',
      'default_value': 'testString',
      'link_status': 'normal',
      'secure': True,
      'immutable': True,
      'hidden': True,
      'required': True,
      'options': ['testString'],
      'min_value': 38,
      'max_value': 38,
      'min_length': 38,
      'max_length': 38,
      'matches': 'testString',
      'position': 38,
      'group_by': 'testString',
      'source': 'testString',
      }
      
      variable_data_model = {
      'name': 'ibmcloud_api_key',
      'value': 'Uqd6nEZEkLRp2VP30H2o-b5b6qcdevpY3w9_g3hs31L5',
      'use_default': True,
      'metadata': variable_metadata_model,
      }
      
      agent_user_state_model = {
      'state': 'enable',
      }
      
      agent_kpi_data_model = {
      'availability_indicator': 'available',
      'lifecycle_indicator': 'consistent',
      'percent_usage_indicator': 'testString',
      'application_indicators': ['testString'],
      'infra_indicators': ['testString'],
      }
      
      response = schematics_service.update_agent_data(
      agent_id='<agent_id>', 
      name='MyDevAgent',
      resource_group='Default',
      version='v1.0.0',
      schematics_location='us-south',
      agent_location='us-south',
      agent_infrastructure=agent_infrastructure_model,
      description='Create Agent',
      tags=['env:test','mytest'],
      agent_metadata=[agent_metadata_info_model],
      agent_inputs=[variable_data_model],
      user_state=agent_user_state_model,
      agent_kpi=agent_kpi_data_model,
      )
      
      agent_data = response.get_result()
      print(json.dumps(agent_data, indent=2))
      
    • const agentInfrastructureModel = {infra_type: 'ibm_kubernetes',
      cluster_id: 'testString',
      cluster_resource_group: 'testString',
      cos_instance_name: 'testString',
      cos_bucket_name: 'testString',
      cos_bucket_region: 'testString',
      };
      
      const agentMetadataInfoModel = {
      name: 'purpose',
      value: ['git', 'terraform', 'ansible'],
      };
      
      const variableMetadataModel = {
      type: 'boolean',
      aliases: ['testString'],
      description: 'testString',
      cloud_data_type: 'testString',
      default_value: 'testString',
      link_status: 'normal',
      secure: true,
      immutable: true,
      hidden: true,
      required: true,
      options: ['testString'],
      min_value: 38,
      max_value: 38,
      min_length: 38,
      max_length: 38,
      matches: 'testString',
      position: 38,
      group_by: 'testString',
      source: 'testString',
      };
      
      const variableDataModel = {
      name: 'testString',
      value: 'testString',
      use_default: true,
      metadata: variableMetadataModel,
      };
      
      const agentUserStateModel = {
      state: 'enable',
      };
      
      const agentKpiDataModel = {
      availability_indicator: 'available',
      lifecycle_indicator: 'consistent',
      percent_usage_indicator: 'testString',
      application_indicators: ['testString'],
      infra_indicators: ['testString'],
      };
      
      const params = {
      agentId: 'AgentFromNode.soA.3c2f',
      name: 'AgentFromNode',
      resourceGroup: 'Default',
      version: 'v1.0.0',
      schematicsLocation: 'us-south',
      agentLocation: 'us-south',
      agentInfrastructure: agentInfrastructureModel,
      description: 'New Description',
      tags: ['testString'],
      agentMetadata: [agentMetadataInfoModel],
      agentInputs: [variableDataModel],
      userState: agentUserStateModel,
      agentKpi: agentKpiDataModel,
      xFeatureAgents: true,
      };
      
      schematicsService
      .updateAgentData(params)
      .then(response => {
      console.log(response.result);
      })
      .catch(err => {
      console.warn(err);
      });
      
    • agentInfrastructureModel := new(schematicsv1.AgentInfrastructure) agentInfrastructureModel.InfraType = core.StringPtr("ibm_kubernetes")
      agentInfrastructureModel.ClusterID = core.StringPtr("testString")
      agentInfrastructureModel.ClusterResourceGroup = core.StringPtr("testString")
      agentInfrastructureModel.CosInstanceName = core.StringPtr("testString")
      agentInfrastructureModel.CosBucketName = core.StringPtr("testString")
      agentInfrastructureModel.CosBucketRegion = core.StringPtr("testString")
      
      agentMetadataInfoModel := new(schematicsv1.AgentMetadataInfo)
      agentMetadataInfoModel.Name = core.StringPtr("purpose")
      agentMetadataInfoModel.Value = []string{"git", "terraform", "ansible"}
      
      variableMetadataModel := new(schematicsv1.VariableMetadata)
      variableMetadataModel.Type = core.StringPtr("boolean")
      variableMetadataModel.Aliases = []string{"testString"}
      variableMetadataModel.Description = core.StringPtr("testString")
      variableMetadataModel.CloudDataType = core.StringPtr("testString")
      variableMetadataModel.DefaultValue = core.StringPtr("testString")
      variableMetadataModel.LinkStatus = core.StringPtr("normal")
      variableMetadataModel.Secure = core.BoolPtr(true)
      variableMetadataModel.Immutable = core.BoolPtr(true)
      variableMetadataModel.Hidden = core.BoolPtr(true)
      variableMetadataModel.Required = core.BoolPtr(true)
      variableMetadataModel.Options = []string{"testString"}
      variableMetadataModel.MinValue = core.Int64Ptr(int64(38))
      variableMetadataModel.MaxValue = core.Int64Ptr(int64(38))
      variableMetadataModel.MinLength = core.Int64Ptr(int64(38))
      variableMetadataModel.MaxLength = core.Int64Ptr(int64(38))
      variableMetadataModel.Matches = core.StringPtr("testString")
      variableMetadataModel.Position = core.Int64Ptr(int64(38))
      variableMetadataModel.GroupBy = core.StringPtr("testString")
      variableMetadataModel.Source = core.StringPtr("testString")
      
      variableDataModel := new(schematicsv1.VariableData)
      variableDataModel.Name = core.StringPtr("testString")
      variableDataModel.Value = core.StringPtr("testString")
      variableDataModel.UseDefault = core.BoolPtr(true)
      variableDataModel.Metadata = variableMetadataModel
      
      agentUserStateModel := new(schematicsv1.AgentUserState)
      agentUserStateModel.State = core.StringPtr("enable")
      
      agentKpiDataModel := new(schematicsv1.AgentKPIData)
      agentKpiDataModel.AvailabilityIndicator = core.StringPtr("available")
      agentKpiDataModel.LifecycleIndicator = core.StringPtr("consistent")
      agentKpiDataModel.PercentUsageIndicator = core.StringPtr("testString")
      agentKpiDataModel.ApplicationIndicators = []interface{}{"testString"}
      agentKpiDataModel.InfraIndicators = []interface{}{"testString"}
      
      result, detailedResponse, err := schematicsService.UpdateAgentData(&schematicsv1.UpdateAgentDataOptions{
      AgentID:             core.StringPtr("<agent_id>"),
      XFeatureAgents:      core.BoolPtr(true),
      Name:                core.StringPtr("MyDevAgentNithin"),
      ResourceGroup:       core.StringPtr("Default"),
      Version:             core.StringPtr("v1.0.0"),
      SchematicsLocation:  core.StringPtr("us-south"),
      AgentLocation:       core.StringPtr("us-south"),
      AgentInfrastructure: agentInfrastructureModel,
      Description:         core.StringPtr("Create Agent"),
      Tags:                []string{"testString"},
      AgentMetadata:       []schematicsv1.AgentMetadataInfo{*agentMetadataInfoModel},
      AgentInputs:         []schematicsv1.VariableData{*variableDataModel},
      UserState:           agentUserStateModel,
      AgentKpi:            agentKpiDataModel,
      })
      if err != nil {
      fmt.Printf("Failed to create the agent : %v and the response is %s", err, detailedResponse)
      }
      
      w, err := json.Marshal(result)
      fmt.Print("Agents:", string(w)))
      

    Response

    The agent details, with user inputs and system generated data.

    Status Code

    • Successfully Updated the agent

    • 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

    • 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": "agent-beta1-testing",
        "description": "New Description",
        "resource_group": "ba8818923fe846e6a8fb5c6d72075768",
        "tags": [
          "env:prod",
          "mytest"
        ],
        "version": "v1.0.0",
        "schematics_location": "us-south",
        "agent_location": "us-south",
        "user_state": {
          "state": "enable",
          "set_by": "test@in.ibm.com",
          "set_at": "2023-03-16T06:12:13.684Z"
        },
        "agent_crn": "crn:v1:bluemix:public:schematics:us-south:a/<crn_value>:agent:agent-beta1-testing.soA.748e",
        "id": "agent-beta1-testing.soA.748e",
        "created_at": "2023-03-16T06:12:13.684Z",
        "creation_by": "test@in.ibm.com",
        "updated_at": "1901-01-01T00:00:00.000Z",
        "system_state": {
          "status_code": "draft"
        }
      }

    Delete agent

    Use this API to disable and delete the agent. Follow the steps to retrieve your IAM access token and authenticate with IBM Cloud Schematics by using the API. For more information about frequently asked questions, see FAQ and Troubleshooting guide.

    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/agents/{agent_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

    • Agent ID to get the details of agent

    • curl -X DELETE https://schematics.cloud.ibm.com/v2/agents/<agent_id>   -H 'Authorization: Bearer <Auth Key>'   -H 'X-Feature-Agents: true'   -H 'refresh_token: <refresh_token>'
    • DeleteAgentDataOptions deleteAgentDataOptions = new DeleteAgentDataOptions.Builder().xFeatureAgents(true)
      .agentId("<agent_id>")
      .build();
      
      Response<Void> response = service.deleteAgentData(deleteAgentDataOptions).execute();
      
      Void agentList = response.getResult();
      System.out.println(agentList);  
      
    • response =  schematics_service.delete_agent_data("<agent_id>")agent_list = response.get_result()
      
      print(json.dumps(agent_list, indent=2))                     
      
    • const params = {xFeatureAgents: true,
      agentId: "<agent_id>",
      };
      
      schematicsService
      .deleteAgentData(params)
      .then(response => {
      console.log(response.result);
      })
      .catch(err => {
      console.warn(err);
      });  
      
    • result, detailedResponse, err :=  schematicsService.GetAgentData(&schematicsv1.GetAgentDataOptions{XFeatureAgents: core.BoolPtr(true),
      AgentID:        core.StringPtr("<agent_id>"),
      })
      if err != nil {
      fmt.Printf("Failed to get the agent data : %v and the response is %s", err, detailedResponse)
      }
      
      w, err := json.Marshal(result)
      fmt.Print("Agents:", string(w))  
      

    Response

    Status Code

    • Successfully deleted the agent

    • 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 was not found

    • 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 agent versions

    Retrieve the list of agent version's available to be deployed. For more information about supported API endpoints, see API endpoint.

    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/agents/versions

    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 --request GET \ --url https://schematics.cloud.ibm.com/v2/agents/versions \ --header 'authorization: Bearer <access_key>' \ --header 'refresh_token: <refresh_token>' \ --header 'x-feature-agents: true'

    Response

    Agent versions available to be deployed

    Status Code

    • Successfully got the agent versions.

    • 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 was not found

    • 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
    • {
        "supported_agent_versions": [
          {
            "display_name": "v1.0.0",
            "agent_version": "1.0.0"
          },
          {
            "display_name": "v1.0.0-beta2",
            "agent_version": "1.0.0-beta2"
          }
        ]
      }

    Get pre-requisite scanner job status

    Use get pre-requisite scanner job status API for deploying an agent by using the agent_id, job_id. The API results the status as pending, in-progress, success, or failed in a string format. For more information about supported API endpoints, see API endpoint.

    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/agents/{agent_id}/prs

    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

    • Agent ID to get the details of agent

    • curl --request GET \ --url https://schematics.cloud.ibm.com/v2/agents/<agent_id>/prs \ --header 'authorization: Bearer <access_key>' \ --header 'refresh_token: <refresh_token>' \ --header 'x-feature-agents: true'

    Response

    Run a pre-requisite scanner for deploying agent.

    Status Code

    • Successfully retrieved pre-requisite scanner job status.

    • 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

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

    Run pre-requisite scanner job

    Use run pre-requisite scanner job API before deploying an agent. The API results the agent prs job updation time with the E-mail address and the status in a string format. For more information about supported API endpoints, see API endpoint.

    Authorization

    Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see [Schematics service access roles and required permissions](https://cloud.ibm.com/docs/schematics?topic=schematics-access#access-roles).
    PUT /v2/agents/{agent_id}/prs

    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

    • Agent ID to get the details of agent

    Query Parameters

    • Equivalent to -force options in the command line, default is false

    • curl --request PUT \ --url https://schematics.cloud.ibm.com/v2/agents/<agent_id>/prs \ --header 'authorization: Bearer <access_key>' \ --header 'refresh_token: <refresh_token>' \ --header 'x-feature-agents: true'

    Response

    Run a pre-requisite scanner for deploying agent.

    Status Code

    • Successfully started pre-requisite scanner job.

    • 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

    • 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 agent health check job

    Use get agent health check job API to retrieve the agent health check job status based on the agent ID. For more information about supported API endpoints, see API endpoint.

    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/agents/{agent_id}/health

    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

    • Agent ID to get the details of agent

    • curl --request GET \ --url https://schematics.cloud.ibm.com/v2/agents/<agent_id>/health \ --header 'authorization: Bearer <access_key>' \ --header 'refresh_token: <refresh_token>' \ --header 'x-feature-agents: true'

    Response

    Agent health check

    Status Code

    • Successfully retrieved agent health check job status

    • 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

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

    Run agent health check

    Use run agent health check job API to execute an agent health check job based on the agent ID. For more information about supported API endpoints, see API endpoint.

    Authorization

    Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see [Schematics service access roles and required permissions](https://cloud.ibm.com/docs/schematics?topic=schematics-access#access-roles).
    PUT /v2/agents/{agent_id}/health

    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

    • Agent ID to get the details of agent

    Query Parameters

    • Equivalent to -force options in the command line, default is false

    • curl --request PUT \ --url https://schematics.cloud.ibm.com/v2/agents/<agent_id>/health \ --header 'authorization: Bearer <access_key>' \ --header 'refresh_token: <refresh_token>' \ --header 'x-feature-agents: true'

    Response

    Agent health check

    Status Code

    • Successfully started running the agent health check job

    • 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

    • 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 agent deployment job

    Use get agent deployment job API to retrieve the agent deployment job status based on the agent ID. For more information about supported API endpoints, see API endpoint.

    Authorization

    Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see [Schematics service access roles and required permissions](https://cloud.ibm.com/docs/schematics?topic=schematics-access#access-roles).
    GET /v2/agents/{agent_id}/deploy

    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

    • Agent ID to get the details of agent

    • curl --request GET \ --url https://schematics.cloud.ibm.com/v2/agents/<agent_id>/deploy \ --header 'authorization: Bearer <access_key>' \ --header 'refresh_token: <refresh_token>' \ --header 'x-feature-agents: true'

    Response

    Post-installations checks for Agent health.

    Status Code

    • Successfully retrieved agent deployment job details

    • 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

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

    Run the agent deployment job

    Use run agent deployment job API to execute the agent deployment job based on the agent ID. For more information about supported API endpoints, see API endpoint.

    Authorization

    Schematics support generic authorization for its resources. For more information, about Schematics access and permissions, see [Schematics service access roles and required permissions](https://cloud.ibm.com/docs/schematics?topic=schematics-access#access-roles).
    PUT /v2/agents/{agent_id}/deploy

    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

    • Agent ID to get the details of agent

    Query Parameters

    • Equivalent to -force options in the command line, default is false

    • curl --request PUT \ --url https://schematics.cloud.ibm.com/v2/agents/<agent_id>/deploy \ --header 'authorization: Bearer <access_key>' \ --header 'refresh_token: <refresh_token>' \ --header 'x-feature-agents: true'

    Response

    Post-installations checks for Agent health.

    Status Code

    • Successfully ran agent deployment job

    • 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

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

    Delete resources provisioned by agent

    Use this API to destroy the resources provisioned for running an agent.

    DELETE /v2/agents/{agent_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.

    • The IAM refresh token for the user or service identity.

      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

    • Agent ID to get the details of agent

    Response

    Status Code

    • Successfully accepted the request to delete the resources

    • 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 was not found

    • 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 a KMS settings

    Retrieve the kms instance that is integrated with Schematics for the byok and kyok. For each geographic location supported in Schematics we can have different kms settings. For example US and EU will have different kms settings.

    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/settings/kms

    Auditing

    Calling this method generates the following auditing event.

    • schematics.kms_settings.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.

    Query Parameters

    • The location of the Resource

    • curl --location --request GET  http://us-south.schematics.cloud.ibm.com/v2/settings/kms?location=US --header "Authorization: <access_token> "—header “Content-Type: application/json "
    • GetKmsSettingsOptions getKmsSettingsOptions = new  GetKmsSettingsOptions.Builder()
      .location("US")
      .build();
      Response<KMSSettings> response =  service.getKmsSettings(getKmsSettingsOptions).execute();
      KMSSettings kmsSettings =  response.getResult();
      
      System.out.println(kmsSettings);
    • kms_settings = schematics_service.get_kms_settings(
        location='US'
        ).get_result()
      print(json.dumps(kms_settings, indent=2))
    • const params = {
        location: 'US',
      };
      
      schematicsService.getKmsSettings(params)
      .then(res => {
      console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
      console.warn(err)
      });
      
    • getKmsSettingsOptions := schematicsService.NewGetKmsSettingsOptions(
      "testString",
      )
      getKmsSettingsOptions.SetLocation("US")
      kmsSettings, response, err := schematicsService.GetKmsSettings(getKmsSettingsOptions)
      if err != nil {
      panic(err)
      }
      b, _ := json.MarshalIndent(kmsSettings, "", "  ")
      fmt.Println(string(b))
      fmt.Println(response)

    Response

    User defined kms settings information.

    Status Code

    • Successfully retrieved the kms settings.

    • 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 kms settings not found.

    • 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
    • {
        "location": "US",
        "encryption_scheme": "byok",
        "resource_group": "Default",
        "primary_crk": {
          "kms_name": "Key Protect-xxx",
          "key_crn": "crn:v1:public:kms:us-south:a/010101010:key:3a14ceaf-c679-455d-10101010",
          "kms_private_endpoint": "your private end point",
          "key_name": "rootk123"
        }
      }

    Update a KMS settings

    Replace or Update kms settings for a given location can be updated. Note you can update the kms settings only once. For example, if you use an API endpoint for a geography, such as North America, only kms settings for that region can be retrieved.

    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 /v2/settings/kms

    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.

    Options to be provided with updating kms settings.

    • curl --location --request PUT https://schematics.cloud.ibm.com/v2/settings/kms?location=US --header "Authorization: <access_token> "—header “Content-Type: application/json "  --data-raw "{"location": "your-location", "encryption_scheme": "byok or kyok", "resource_group": "Default", "primary_crk": {"kms_name": "Key Protect-xxx","key_crn": "crn:v1:public:kms:us-south:a/010101010:key:3a14ceaf-c679-455d-10101010,","kms_private_endpoint": "<your_private_endpoint_url>"}}"
    • KMSSettingsPrimaryCrk setting = new KMSSettingsPrimaryCrk.Builder()
      .kmsName("Key Protect-2h")
      .keyCrn("crn:v1:bluemix:public:kms:us-south:a/6dd8772094b442c98deb5fe293e8f6cf:295f5cb7-07a1-4a21-b458-16a5554ab523:key:4795a33b-5923-421c-a6ea-fc884d5faf5a")
      .kmsPrivateEndpoint("https://private.us-south.kms.cloud.ibm.com")
      .build();
      UpdateKmsSettingsOptions updateKmsSettingsOptions = new UpdateKmsSettingsOptions.Builder()
      .location("US")
      .encryptionScheme("byok")
      .resourceGroup("Default")
      .primaryCrk(setting)
      .build();
      Response<KMSSettings> response1 = service.updateKmsSettings(updateKmsSettingsOptions).execute();
      KMSSettings kmsSettings1 = response1.getResult();
      System.out.println(kmsSettings1);
      
    • kms_settings = schematics_service.update_kms_settings(
      location='US',
      encryption_scheme= "byok",
      resource_group= "Default",
      primary_crk= {
      'kms_name': "Key Protect-2h",
      'key_crn': "crn:v1:bluemix:public:kms:us-south:a/6dd8772094b442c98deb5fe293e8f6cf:295f5cb7-07a1-4a21-b458-16a5554ab523:key:4795a33b-5923-421c-a6ea-fc884d5faf5a",
      'kms_private_endpoint': "https://private.us-south.kms.cloud.ibm.com",
      }
      ).get_result()
      print(json.dumps(kms_settings, indent=2))
      
    • const params = {
      encryptionScheme:'byok',
      location:'US',
      resourceGroup:'Default',
      primaryCrk:{
      kms_name:"Key Protect-2h",
      key_crn:"crn:v1:bluemix:public:kms:us-south:a/6dd8772094b442c98deb5fe293e8f6cf:295f5cb7-07a1-4a21-b458-16a5554ab523:key:4795a33b-5923-421c-a6ea-fc884d5faf5a",
      kms_private_endpoint:"https://private.us-south.kms.cloud.ibm.com"
      }
      };
      schematicsService.updateKmsSettings(params)
      .then(res => {
      console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
      console.warn(err)
      });
      
    • updateKmsSettingsOptions := schematicsService.NewUpdateKmsSettingsOptions()
      updateKmsSettingsOptions.SetLocation("US")
      updateKmsSettingsOptions.SetEncryptionScheme("byok")
      updateKmsSettingsOptions.SetResourceGroup("Default")
      primaryCrk := &schematicsv1.KMSSettingsPrimaryCrk{
      KmsName:            core.StringPtr("Key Protect-w2"),
      KeyCrn:             core.StringPtr("<crn:v1:staging"),
      KmsPrivateEndpoint: core.StringPtr("https://qa.private.us-south.kms.cloud.ibm.com"),
      }
      updateKmsSettingsOptions.SetPrimaryCrk(primaryCrk)
      kmsSettings, response, err := schematicsService.UpdateKmsSettings(updateKmsSettingsOptions)
      if err != nil {
      fmt.Println(err)
      }
      b, _ := json.MarshalIndent(kmsSettings, "", "  ")
      fmt.Println(string(b))
      fmt.Println(response) 
      

    Response

    User defined kms settings information.

    Status Code

    • Successfully retrieved the kms settings.

    • Bad request - Verify the location, payload, or query parameters in the 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
    • {
        "location": "US",
        "encryption_scheme": "byok",
        "resource_group": "Default",
        "primary_crk": {
          "kms_name": "Key Protect-xxx",
          "key_crn": "crn:v1:public:kms:us-south:a/010101010:key:3a14ceaf-c679-455d-10101010",
          "kms_private_endpoint": "your private end point URL",
          "key_name": "rootk1"
        }
      }

    List KMS instances

    Lists the kms instances of your IBM Cloud account to find your Key Protect or Hyper Protect Crypto Services by using the location and encrypted scheme.

    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/settings/kms_instances

    Auditing

    Calling this method generates the following auditing event.

    • schematics.kms_instances.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.

    Query Parameters

    • The encryption scheme to be used

    • The location of the Resource

    • The resource group (by default, fetch from all resource groups) name or ID

    • 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

    • curl --location --request GET  http://schematics.cloud.ibm.com/v2/settings/kms_instances/?location=US&encryption_scheme=byok --header "Authorization: <access_token> "—header "Content-Type: <content-type> "
    • ListKmsOptions listKmsOptions = new ListKmsOptions.Builder()
      .encryptionScheme(“byok”)
      .location("US")
      .build();
      Response<KMSDiscovery> response = service.listKms(listKmsOptions).execute();
      KMSDiscovery kmsDiscovery = response.getResult();
      System.out.println(kmsDiscovery);
      
    • kms_discovery = schematics_service.list_kms(
      encryption_scheme='byok',
      location='US'
      ).get_result()
      print(json.dumps(kms_discovery, indent=2))
      
    • const params = {
      encryptionScheme: 'byok',
      location: 'US',
      };
      schematicsService.listKms(params)
      .then(res => {
      console.log(JSON.stringify(res.result, null, 2));
      })
      .catch(err => {
      console.warn(err)
      });
      
    • listKmsOptions := schematicsService.NewListKmsOptions(
      "testString",
      "testString",
      )
      listKmsOptions.SetLocation("US")
      listKmsOptions.SetEncryptionScheme("byok")
      kmsDiscovery, response, err := schematicsService.ListKms(listKmsOptions)
      if err != nil {
      panic(err)
      }
      b, _ := json.MarshalIndent(kmsDiscovery, "", "  ")
      fmt.Println(string(b))
      fmt.Println(response)
      

    Response

    Discover kms instances in the account based on location.

    Status Code

    • Successfully discovered the KMS instance from the customer account.

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

    • kms instance not found in the account.

    • 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
    • {
        "location": "US",
        "limit": "10",
        "encryption_scheme": "byok",
        "resource_group": "Default",
        "kms_instances": [
          {
            "kms_crn": "crn:v1:public:kms:us-south:a/010101010:key:3a14ceaf-c679-455d-10101010",
            "kms_name": "Key Protect-xxx",
            "keys": [
              {
                "name": "rootk123",
                "crn": "crn:v1::public:kms:us-south:alalalallala1231231la"
              }
            ],
            "public_endpoint": "https://kms.cloud.ibm.com",
            "private_endpoint": "https://kms.cloud.ibm.com"
          }
        ]
      }

    List policies

    Retrieve a list of all policies from the account that you have access. the list of policies 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 policies that are created in us-south or us-east are returned. For more information about supported API endpoints, see API endpoint.

    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/settings/policies

    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

    • Level of details returned by the get method

      Allowable values: [summary,detailed,ids]

    • curl -X --request GET http://schematics.cloud.ibm.com/v2/settings/policies \  --header "Authorization: <access_token> " --header -H "Content-Type: application/json" "Cookie: " 

    Response

    The list of Schematics customization policies.

    Status Code

    • Successfully listed all policies in the account

    • 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": 2,
        "limit": 100,
        "offset": 0,
        "agents": [
          {
            "name": "policy-7004bc1a-d5bf-4908-a34a-46dfd6977722",
            "id": "policy-7004bc1a-d5bf-4908-a34a-46dfd6977722.eaP.ff3c",
            "account": "1f7277194bb748cdb1d35fd8fb85a7cb",
            "description": "Created agent-assignment-policy for the workspace: us-east.workspace.Final_test_ws-3.721df95e, agent: Agent-CLI-Final-Testing.eaA.6416",
            "resource_group": "15a5b53ee3ec4657a311fd8c0392f875",
            "location": "us-east",
            "state": {
              "state": "draft",
              "set_by": "schematics@ibm.com",
              "set_at": "2022-07-11T10:22:53.566Z"
            },
            "policy_kind": "agent_assignment_policy",
            "created_at": "2022-07-11T10:22:53.566Z",
            "updated_at": "1901-01-01T00:00:00.000Z"
          },
          {
            "name": "policy-906e2aca-dc99-4e2b-8329-83d951849769",
            "id": "policy-906e2aca-dc99-4e2b-8329-83d951849769.eaP.d44b",
            "account": "1f7277194bb748cdb1d35fd8fb85a7cb",
            "description": "Created agent-assignment-policy for the workspace: us-east.workspace.agent-binded-cli-final.843f38e0, agent: cli-agent.eaA.8a61",
            "resource_group": "15a5b53ee3ec4657a311fd8c0392f875",
            "location": "us-east",
            "state": {
              "state": "draft",
              "set_by": "schematics@ibm.com",
              "set_at": "2022-07-12T09:03:07.040Z"
            },
            "policy_kind": "agent_assignment_policy",
            "created_at": "2022-07-12T09:03:07.040Z",
            "updated_at": "1901-01-01T00:00:00.000Z"
          }
        ]
      }

    Create a policy account

    Use this API to create a policy using Schematics to select one or more Schematics objects (such as, Workspaces, Action) to deliver targeted Schematics feature. For more information about frequently asked questions, see FAQ and Troubleshooting guide.

    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/settings/policies

    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.

    Create a new policy in account

    • curl -X --request POST http://schematics.cloud.ibm.com/v2/settings/agents  "Authorization: <access_token>" --header "enable_blueprint: true" "Content-Type: application/json" -d "{	"name": "new-policy-dev", "description": "Policy for job execution of secured workspaces on agent1", "resource_group": "Default",	"tags": [	"policy:secured-job"], "location": "us-south",	"policy_kind": "agent_assignment_policy", "policy_target": {	"selector_kind": "ids",	"selector_ids": [	"latest-agent.soA.c4a0"	]	}, "policy_parameter": {		"agent_assignment_policy_parameter": {"selector_kind": "ids","selector_ids": ["us-south.workspace.gb.s91762c7"]}}}""

    Response

    Detailed information about the Schematics customization policy. This policy can be used to customize the behaviour or the core Schematics service.

    Status Code

    • Successfully created the policy

    • 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

    • 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": "new-policy-dev",
        "description": "Policy for job execution of secured workspaces on agent1",
        "resource_group": "Default",
        "tags": [
          "policy:secured-job"
        ],
        "location": "us-south",
        "state": {
          "state": "draft",
          "set_by": "schematics@ibm.com",
          "set_at": "2022-07-12T10:54:16.270Z"
        },
        "policy_kind": "agent_assignment_policy",
        "policy_target": {
          "selector_kind": "ids",
          "selector_ids": [
            "latest-agent.soA.c4a0"
          ]
        },
        "policy_parameter": {
          "agent_assignment_policy_parameter": {
            "selector_kind": "ids",
            "selector_ids": [
              "us-south.workspace.gb.s91762c7"
            ]
          }
        },
        "id": "new-policy-dev.soP.b2de",
        "crn": "crn:v1:bluemix:public:schematics:us-south:a/2g7200134cc638bgh1d35fd8fb85a7cb:8ae4cd72-0k99-416c-b6ce-0b662l520a4p:policy:new-policy-dev.soP.b2de",
        "account": "1f7277194bb748cdb1d35fd8fb85a7cb",
        "created_at": "2022-07-12T10:54:16.270Z",
        "updated_at": "1901-01-01T00:00:00.000Z"
      }

    Get policy

    Retrieve the detailed information of a policy details identified by policy_id. For more information about frequently asked questions, see FAQ and Troubleshooting guide. For more information about supported API endpoints, see API endpoint.

    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/settings/policies/{policy_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

    • ID to get the details of policy

    Query Parameters

    • Level of details returned by the get method

      Allowable values: [summary,detailed,ids]

    • curl -X --request GET http://schematics.cloud.ibm.com/v2/settings/policies/{policy_id}  --header "Authorization: <access_token> " --header -H "Content-Type: application/json" "Cookie: " 

    Response

    Detailed information about the Schematics customization policy. This policy can be used to customize the behaviour or the core Schematics service.

    Status Code

    • Successfully got the policy details

    • 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 was not found

    • 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": "new-policy-dev",
        "description": "Policy for job execution of secured workspaces on agent1",
        "resource_group": "Default",
        "tags": [
          "policy:secured-job"
        ],
        "location": "us-south",
        "state": {
          "state": "draft",
          "set_by": "schematics@ibm.com",
          "set_at": "2022-07-12T10:54:16.270Z"
        },
        "policy_kind": "agent_assignment_policy",
        "policy_target": {
          "selector_kind": "ids",
          "selector_ids": [
            "latest-agent.soA.c4a0"
          ]
        },
        "policy_parameter": {
          "agent_assignment_policy_parameter": {
            "selector_kind": "ids",
            "selector_ids": [
              "us-south.workspace.gb.s91762c7"
            ]
          }
        },
        "id": "new-policy-dev.soP.b2de",
        "crn": "crn:v1:bluemix:public:schematics:us-south:a/2g7200134cc638bgh1d35fd8fb85a7cb:8ae4cd72-0k99-416c-b6ce-0b662l520a4p:policy:new-policy-dev.soP.b2de",
        "account": "1f7277194bb748cdb1d35fd8fb85a7cb",
        "created_at": "2022-07-12T10:54:16.270Z",
        "updated_at": "1901-01-01T00:00:00.000Z"
      }

    Delete policy

    Use this API to delete the policy. Follow the steps to retrieve your IAM access token and authenticate with IBM Cloud Schematics by using the API. For more information about frequently asked questions, see FAQ and Troubleshooting guide.

    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/settings/policies/{policy_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

    • ID to get the details of policy

    • curl -X --request DELETE https://schematics.cloud.ibm.com/v2/settings/policies/{policy_id} --header "Authorization: <access_token> "

    Response

    Status Code

    • Successfully deleted the policy

    • 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 was not found

    • The specified resource is locked, cannot be updated or deleted

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

    Update policy

    Use update policy API to update or replace the policy details by using policy ID. For more information about supported API endpoints, see API endpoint. Follow the steps to retrieve your IAM access token and authenticate with IBM Cloud Schematics by using the API. For more information about frequently asked questions, see FAQ and Troubleshooting guide.

    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/settings/policies/{policy_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

    • ID to get the details of policy

    Update the policy details

    • curl -X --request PATCH http://schematics.cloud.ibm.com/v2/settings/policies/{policy_id} "Authorization: <access_token>" --header "enable_blueprint: true" "Content-Type: application/json" -d "{	"name": "new-policy-dev", "description": "Policy for job execution of secured workspaces on agent1 updated", "resource_group": "Default",	"tags": [	"policy:secured-job"], "location": "us-south",	"policy_kind": "agent_assignment_policy", "policy_target": {	"selector_kind": "ids",	"selector_ids": [	"latest-agent.soA.c4a0"	]	}, "policy_parameter": {		"agent_assignment_policy_parameter": {"selector_kind": "ids","selector_ids": ["us-south.workspace.gb.s91762c7"]}}}""

    Response

    Detailed information about the Schematics customization policy. This policy can be used to customize the behaviour or the core Schematics service.

    Status Code

    • Successfully updated the policy details

    • 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 was not found

    • The specified resource is locked, cannot be updated or deleted

    • 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": "new-policy-dev",
        "description": "Policy for job execution of secured workspaces on agent1 updated",
        "resource_group": "Default",
        "tags": [
          "policy:secured-job"
        ],
        "location": "us-south",
        "state": {
          "state": "draft",
          "set_by": "schematics@ibm.com",
          "set_at": "2022-07-12T10:54:16.270Z"
        },
        "policy_kind": "agent_assignment_policy",
        "policy_target": {
          "selector_kind": "ids",
          "selector_ids": [
            "latest-agent.soA.c4a0"
          ]
        },
        "policy_parameter": {
          "agent_assignment_policy_parameter": {
            "selector_kind": "ids",
            "selector_ids": [
              "us-south.workspace.gb.s91762c7"
            ]
          }
        },
        "id": "new-policy-dev.soP.b2de",
        "crn": "crn:v1:bluemix:public:schematics:us-south:a/2g7200134cc638bgh1d35fd8fb85a7cb:8ae4cd72-0k99-416c-b6ce-0b662l520a4p:policy:new-policy-dev.soP.b2de",
        "account": "1f7277194bb748cdb1d35fd8fb85a7cb",
        "created_at": "2022-07-12T10:54:16.270Z",
        "updated_at": "2022-07-12T11:32:47.012Z"
      }