IBM Cloud Orchestrator, Version 2.5.0.2

Managing entities by using actions

Any action as described in the Managing Entities by using Core Services REST APIs documentation can be started per API. The action must be started in the Core Services REST API. The following procedure is an example of how to start the Edit Project action on a project through API.

Procedure

  1. Get the project provider and the URL for its instances in the instances attribute of the response.

    HTTP method:

    GET

    Example:

    https://ico_server.example.com:443/orchestrator/v2/instancetypes/project 
    {
  "href": "https://ico_server.example.com:443/
orchestrator/v2/instancetypes/project",
  "item": {
    "provider": "com.ibm.orchestrator.core.instance
.providers.openstack.OpenstackProjectProvider",
    "detailsview": {
      "application": "SCOMT",
      "humanservice": "Show Project Details"
    },
    "keyfields": [
      {
        "instanceattribute": "displayname",
        "header": "Name"
      },
      {
        "instanceattribute": "description",
        "header": "Description"
      },
      {
        "instanceattribute": "enabled",
        "header": "Enabled?"
      }
    ],
    "tags": [
      "enabled",
      "disabled"
    ],
    "icon": "Web Icon:glyphicons_232_cloud",
    "type": "admin",
    "name": "project",
    "description": "Show your OpenStack projects.",
    "displayname": "Projects"
  },
  "instances": {
    "href":
 "https://ico_server.example.com:443/orchestrator
/v2/instancetypes/project/instances"
  },
  "services": {
    "href": "https://ico_server.example.com:443/
orchestrator/v2/instancetypes/project/services"
  }
}
  2. Get the instance that you want to manage and find the ID and name. You can also use the API filter to search the name attribute.

    HTTP Method:

    GET

    Example:

    https://ico_server.example.com:443/orchestrator/v2/instancetypes/project/instances
    {
  "href": "https://ico_server.example.com:443
/orchestrator/v2/instancetypes/project/instances",
  "start": 0,
  "limit": 10,
  "total": 4,
  "first": {
    "href": 
"https://ico_server.example.com:443/orchestrator
/v2/instancetypes/project/instances?_limit=10&_start=0"
   },
   "previous": null,
   "next": null,
   "last": {
     "href":
 "https://ico_server.example.com:443
/orchestrator/v2/instancetypes/project/instances?_limit=10&_start=0"
   },
   "items": [
     {
       "href":
 "https://ico_server.example.com:443/
orchestrator/v2/instancetypes/project/instances/
4ae7ade7e4724c69ab90246ea72965e6",
       "item": {
         "enabled": true,
         "domain": "4ae7ade7e4724c69ab90246ea72965e6",
         "tags": [
           "enabled"
         ],
         "icon": null,
         "id": "4ae7ade7e4724c69ab90246ea72965e6",
         "parm": {
           "enabled": true,
           "domain_id": "default",
           "links": {
             "self":
 "http://192.0.2.35:5000/v3/projects
       /4ae7ade7e4724c69ab90246ea72965e6"   },
           "id": "4ae7ade7e4724c69ab90246ea72965e6",
           "name": "admin",
           "description": "admin Tenant"
         },
         "description": "admin Tenant",
         "detailsURL":
 "https://ico_server.example.com:443/teamworks/
executeServiceByName?processApp=SCOMT&serviceName=
Show+Project+Details&tw.local.projectId=
4ae7ade7e4724c69ab90246ea72965e6&tw.local.domainId=
default&tw.local.authUser=admin&tw.local.authDomain=
Default&tw.local.authProject=admin",
         "displayname": "admin"
       }
     },
     ...
   ]
 }
  3. Get the actions that are applicable to projects. Get the link to in the services attribute of the response in step 1. Get the services and find the Edit Project action by name and remember its ID.

    HTTP method:

    GET

    Example:

    https://ico_server.example.com:443/orchestrator/v2/instancetypes/project/services 
    ...
{
   "href": "https://ico_server.example.com:443/
orchestrator/v2/instancetypes/project/services/69",
   "item": {
     "human_service": "Edit Project Action",
     "priority": 0,
     "human_service_app_name": "SCOrchestrator Multi-Tenancy Toolkit",
     "implementation_type": null,
     "created": 1401827772,
     "human_service_app_short_name": "SCOMT",
     "process_app_id": "2066.227c57b3-a5e5-4e5b-a283-c920cf9bed50",
     "acl": [
         ...
      ],
     "name": "Edit Project",
     "ownerid": 0,
     "instancetype": "project",
     "process": "Edit Project Action",
     "operation_type": "singleInstanceAction",
     "human_service_app_id": "2066.227c57b3-a5e5-4e5b-a283-c920cf9bed50",
     "tags": [
       "enabled"
     ],
     "process_app_name": "SCOrchestrator Multi-Tenancy Toolkit",
     "icon": "act16_return",
     "updated": 1401827772,
     "id": 69,
     "process_app_short_name": "SCOMT",
     "description": "Edit the project details",
     "category": 31
   }
 },
...
  4. Start the action with the ID from step 3, passing the ID of the selected instance (project) from step 2 in the request body. The call returns a task that is in the state NEW and a new ID.
    Note: For all actions of type "createInstance", the ID of the domain must be passed in the "instances" array of the PUT request.

    HTTP method:

    POST

    Body:

    {
  "instances": ["default"]
}

    Example:

    https://ico_server.example.com:443/orchestrator/v2/instancetypes/project/services/69/launch
    {
  "updated_iso": "1970-01-01T01:00:00+0100",
  "description_message": "HS_OFFERING_INVOCATION",
  "domain": "Default",
  "message": "Launched",
  "created": 1402569924045,
  "error": null,
  "user": "admin",
  "parm": {
    "plan": {
      "human_service": "Edit Project Action",
      "priority": 0,
      "human_service_app_name": "SCOrchestrator Multi-Tenancy 
                                 Toolkit",
      "implementation_type": null,
      "created": 1401827772,
      "human_service_app_short_name": "SCOMT",
      "process_app_id": "2066.227c57b3-a5e5-4e5b-a283-c920cf9bed50",
      "acl": [
        ...
      ],
      "name": "Edit Project",
      "ownerid": 0,
      "instancetype": "project",
      "process": "Edit Project Action",
      "operation_type": "singleInstanceAction",
      "human_service_app_id": "2066.227c57b3-a5e5-4e5b-a283-
                               c920cf9bed50",
      "tags": [
        "enabled"
      ],
      "process_app_name": "SCOrchestrator Multi-Tenancy Toolkit",
      "icon": "act16_return",
      "updated": 1401827772,
      "id": 69,
      "process_app_short_name": "SCOMT",
      "description": "Edit the project details",
      "category": 31
    },
    "instances": [
      "default"
    ]
  },
  "created_iso": "2014-06-12T12:45:24+0200",
  "status_localized": "New",
  "error_message": null,
  "status": "NEW",
  "eventTopic": "com/ibm/orchestrator/serviceinstance/plan
                 /ibm_bpm_process",
  "delayInSeconds": 0,
  "project": "admin",
  "id": "1521",
  "updated": 0,
  "redirect": "/teamworks/executeServiceByName?
processApp=SCOMT&serviceName=Edit+Project+Action&tw.
local.operationContextId=1521",
   "description": {
     "resourceBundle": "com.ibm.orchestrator.messages.
                        orchestratormessages",
     "message": "HS_OFFERING_INVOCATION",
     "messageKey": "HS_OFFERING_INVOCATION",
     "args": [
       "Edit Project"
     ]
   }
 }
  5. Set the parameters of the task that are the input for the action. Then, set the status of the task to QUEUED to queue the task for execution. In the body, the description is set to test and the other attributes remain the same.

    HTTP method:

    PUT

    Body:

    {
"status":"QUEUED",
          "parm":{"OperationParameter":"<variable type=\"Project\">\n
            <name type=\"String\"><![CDATA[admin]]><\/name>\n
            <description type=\"String\"><![CDATA[test]]>
            <\/description>\n
            <enabled type=\"Boolean\"><![CDATA[true]]><\/enabled>\n
            <id type=\"String\"><![CDATA[
                    4ae7ade7e4724c69ab90246ea72965e6]]><\/id>\n
            <domainId type=\"String\"><![CDATA[default]]>
                           <\/domainId>\n<\/variable>"}
    }

    Example:

    https://ico_server.example.com:443/kernel/tasks/1521

  6. Check whether the task succeeded or failed. The status switches to RUNNING. If the task succeeds the status says COMPLETED. If the task fails the status says FAILED and an error_message is shown. In the example, the process completed.

    HTTP method:

    GET

    Example:

    https://ico_server.example.com:443/kernel/tasks/1521
    {
   "error_message": "CTJCO0002I: Business process instance 79 
                     completed successfully.",
   "status": "COMPLETED",
}
  7. Verify whether the action applied the changes on the entity. Finally, it is possible to ensure if the change happened on the instance.

    HTTP method:

    GET

    Example:

    https://ico_server.example.com:443/orchestrator/v2/instancetypes/project/instances/4ae7ade7e4724c69ab90246ea72965e6
    {
  "href": "https://ico_server.example.com:443/orchestrator/v2
           /instancetypes/project
           /instances/4ae7ade7e4724c69ab90246ea72965e6",
  "item": {
    "enabled": true,
    "domain": "4ae7ade7e4724c69ab90246ea72965e6",
    "tags": [
      "enabled"
    ],
    "icon": null,
    "id": "4ae7ade7e4724c69ab90246ea72965e6",
    "parm": {
      "enabled": true,
      "domain_id": "default",
      "links": {
        "self": "http://192.0.2.35:5000/v3/projects
                 /4ae7ade7e4724c69ab90246ea72965e6"
      },
      "id": "4ae7ade7e4724c69ab90246ea72965e6",
      "name": "admin",
      "description": "test"
    },
    "description": "test",
    "detailsURL":
 "https://ico_server.example.com:443
/teamworks/executeServiceByName?processApp=SCOMT&serviceName
=Show+Project+Details&tw.local.
projectId=4ae7ade7e4724c69ab90246ea72965e6&tw.local.
domainId=default&tw.local.authUser=admin&tw.local
.authDomain=Default&tw.local.authProject=admin",
     "displayname": "admin"
   }
 }
Parent topic: Configuration providers REST API