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 specifications, 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.

Manually defining actions vs. autogenerated ones​

In most cases, you don’t need to manually define create, update, or delete actions.

Instead, we recommend enabling autogenerated actions directly in your service (or link) specification by setting "use_default_actions": true.

This approach keeps your actions in sync with the spec and requires less maintenance.

Standard actions are autogenerated and cannot be edited directly. If you need to modify them, you must update the service specification schema instead.

To learn how to enable autogenerated actions, see:

Still, there are situations where defining action specifications manually is the right choice—especially when creating custom actions or needing to update standard actions. This page covers how to do that.

Parameters and results​

If you're defining action specifications manually, for each action you'll have to define these fields:

  • parameters: the input requirements for the action, expressed as a JSON 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.

Note: See our Troubleshooting page for more info.

You can't create standard actions if action specifications already exist​

Autogenerated standard actions help simplify the service creation workflow, allowing you to get started with a basic setup quickly.

However, if you've already created and linked action specifications to a service, you won't be able to enable standard actions by setting use_default_actions to true.

This ensures there's no conflict between manually defined actions and autogenerated ones.

How to override standard actions​

Standard actions cannot be modified directly in the service specification, but you can override them by creating action specifications manually.

  1. Set use_default_actions to false in your service specification.
  2. Update action specifications for create, update, and delete actions.

This setup tells the platform to use your manually-defined actions instead of the autogenerated ones.

How deleting services work​

To avoid orphaned infrastructure and unnecessary costs, the following rules apply to deleting a services:

  • If a service has a delete action, that action must be executed before deletion.
  • Alternatively, deletion can be forced with a specific parameter (force=true).

Trying to delete a service without executing the delete action results in an error unless the override is used.

Here's an example:

np link delete --id <LINK_ID> --force true

For more info, see our API reference docs.

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 where it’s safe to retry an action after failure, you can use the retryable field set to true in the action specification. This tells nullplatform that the action can be triggered again under certain conditions.

Here’s what you need to know:

Action typeConsiderations
CreateThe service instance must have previously failed to create. You can’t retry a create action on an already successful or existing one.
UpdateThe service must have been successfully created before the failed update.
DeleteThe delete action is retryable only if no prior delete action has succeeded.
CustomThe service must have been successfully created before retrying.
note

Autogenerated standard actions follow these retryability rules by default:

  • create actions are not retryable
  • update and delete actions are retryable

How to retry actions​

You can retry failed service actions from the UI or via API:

From the UI:

  1. Go to Development > Services.
  2. Click Manage > History on the service that failed.
  3. Click Retry to re-run the action with the same inputs.

From the API or CLI:

Send a POST request to the Create a service action endpoint with the same parameters.