Skip to main content

Action specifications

Before you start

If you haven't done it yet, read about services' main concepts.

Also have these handy reference:

This guide applies to services and links

Creating actions for services and links is exactly the same process. Unless stated otherwise, every time we refer to services or service specifications you can automatically assume the same applies to links and link specifications.

Design your action specifications​

Now that you have your service specification, you have to bring it to life by designing create, update, and delete actions.

Here are some design questions to answer:

QuestionGuidance
Which input parameters do I need to ask to create the service?This is a central design question that will determine the content of the JSON schema under the attributes field.
Which parameters will I allow to be edited?Be mindful of the underlying capabilities of your cloud-based services. Also, be careful not to allow changing parameters which cannot be changed in-place and would trigger a resource re-creation by your IaC tool.
Which custom actions do I want to provide?These will be actions that serve a specific operational purpose such as "Manually push an event to the queue".
Do I need to store results for my action?Results play a key role as they connect actions to the service specifications. Also, custom action's results are displayed to the end-user for easier interpretation.

Design all required actions​

Services usually require actions to create, update, or delete the service. On top of this, you can also add your own custom actions. This means that you'll likely have to design and create several actions for a service.

Therefore, your actions need to declare one of these action types: create, update, and delete, unless you are creating a custom action, which requires an action of type custom.

Parameters and results​

For each action, you'll have to define these fields:

  • parameters: the input requirements for the action , expressed as aJSON schema.

  • results: the expected output of the action, also expressed as a JSON schema.

    UI Schema

    See the UI schema reference section for more information on how to manipulate the fields in the UI.

Action specifications​

To create, update, or destroy a service, you will typically run an action (note that this is optional but very usual).

If you're interacting with the service through the UI, nullplatform will look up for the corresponding action specifications and will create a new action instance. If you're doing a custom integration, you have to call these actions explicitly.

Action types

Use the type field on the action specification to distinguish between create, update, delete, and custom actions.

In the following subsections we provide examples for each of these action types and review our API reference for more info.

Create​

np service-specification action-specification create \
 --serviceSpecificationId $service_spec_id \
 --body '{
    "name": "Create my service action spec",
    "type": "create",
    "parameters": {       // defines the input requirements for the action.
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    },
    "results": {        // defines the expected output of the action.
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

Update​

np service-specification action-specification create \
 --serviceSpecificationId $service_spec_id \
 --body '{
    "name": "Create my service update action spec",
    "type": "update",
    "parameters": {       // defines the input requirements for the action.
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    },
    "results": {        // defines the expected output of the action.
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

Delete​

np service-specification action-specification create \
 --serviceSpecificationId $service_spec_id \
 --body '{
    "name": "Create my service delete action spec",
    "type": "delete",
    "parameters": {      // defines the input requirements for the action.
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    },
    "results": {       // defines the expected output of the action.
      "schema": {
        "type": "object",
        "properties": {}
      },
      "values": {}
    }
  }'

Custom​

np service-specification action-specification create \
 --serviceSpecificationId $service_spec_id \
 --body '{
    "name": "Create my service custom action spec",
    "type": "custom",
    "parameters": {       // defines the input requirements for the action.
      "schema": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string"
          },
          "delay_in_seconds": {
            "type": "integer",
            "default": 0
          }
        }
      },
      "values": {}
    },
    "results": {       // defines the expected output of the action.
      "schema": {
        "type": "object",
        "properties": {
          "message_id": {
            "type": "string"
          }
        }
      },
      "values": {}
    }
  }'

Some attributes to consider​

Let's do more digging into some of the fields we specify on the POST and PATCH:

  • results has two fields:

    • schema: a JSON schema for the results.
    • results: the actual results for the action.

  • retryable: set to true if you want the action to be able to be triggered again upon failures (see Retryable actions section).

Important rules about actions​

What happens when an action fails?​

When a create, update, or delete actions fails, the service instance gets modified and is placed in a "failed" state which requires manual intervention to assess if the service needs repairing or can be placed again in an active state. Therefore, when these actions fail, users are prevented from running any of these actions again.

Running actions more than once​

Only one action at a time​

To prevent failure scenarios, we reject running a create, update, or delete action while there's another action of the same type already running. Note that this rule does not apply for custom actions.

Retryable actions​

For services for which is safe to retry an action upon failure, you can use the retryable field in the action specification to tell nullplatform that this action can be triggered again, but you need to have these rules in mind:

Action typeConsiderations
CreateIn order to retry a create action, a non successful create action must have happened. You cannot try to create 2 times the same instance.
UpdateIn order to retry an update action, the instance must have been successfully created before.
DeleteThis action is retryable only if no other successful delete actions have happened.
CustomThe service must have been successfully created before retrying.