Accessing and Manipulating Records

All content that is stored in Engine is stored in the form of records. This includes flow scripts, files, messages, users, executions and anything else you or the system create on the platform. All records can be accessed and manipulated with the same methods.

This section describes three methods for creating, accessing, manipulating, and deleting records. More detailed information can be found in the REST API documentation, and the Flow-API documentation.

Creating

Via the User Interface

1. Press "+ Create" and select the type of record you like to create.

The create button

2. The new record is opened in the main section.

Via the REST API

Send a POST request to:

https://<your-workspace-name>.cloudomation.com/api/latest/<record-type>

The JSON payload should contain all fields you wish to set.

Via the Engine Flow-API

import flow_api

def handler(system: flow_api.System, this: flow_api.Execution, inputs: dict):
    system.<record-type>('name of the new record').save()
    # for example:
    system.setting('my-new-setting').save()
    # you can set fields of the new record:
    system.setting('my-new-setting').save(value=42, description='some number')

Please note, that .save() is necessary for the record to be created.

danger

The save method overwrites existing records with the same name and type, unless they're read-only. If that is not intended, you can first check for the existence of a record with the same name and type, before calling the save method.

warning

Engine resource names must not start or end with a blank. Engine will implicitly remove any leading or trailing blanks from resource names.

Listing

Via the User Interface

1. Switch to the workspace dashboard by clicking the Engine logo in the menu.
2. Scroll down to the resource tabs.

Via the REST API

Send a GET request to:

$ curl https://\<your-workspace-name>.cloudomation.com/api/latest/\<record-type>

You can use filter expressions:

$ curl 'https://\<your-workspace-name>.cloudomation.com/api/latest/\<record-type>?filter={"field":"name","op":"like","value":"my-%"}'

Via the Engine Flow-API

warning

Listing via the Flow-API will return all records which exist when the listing starts. This means when records are created during the listing, they will not be included in a currently running listing. Also, when records are deleted during the listing, they are still returned. Make sure to handle the ResourceNotFoundError while iterating over a listing result.

Use the following method:

import flow_api

def handler(system: flow_api.System, this: flow_api.Execution, inputs: dict):
    # for record in system.<record-type>s():
    #    # do something with "record"

    # for example:
    this.log(all_webhooks=list(system.webhooks()))
    # you can use filter expressions
    this.log(all_enabled_webhooks=list(system.webhooks(filter_={
        'field': 'is_enabled',
        'op': 'eq',
        'value': 'True',
    })))

important

The maximum number of records that are returned with one call is 1000. Therefore, if you have more than 1000 records of a specific record type you need to use multiple iterations combined with offset and order to list all records.

The parameters for system.<record-type>s are as follows:

Parameter	Description	Default value
fields	Which fields to return (string of comma-separated field-names).	None
limit	How many records to return.	1000
offset	How many records to skip before returning records.	0
filter_	Filter to limit the results.	None
order	How to order the records before applying limit and offset (string of comma-separated field-names).	None
allow_normal	If to include normal records in the response (That is records which are not deleted).	True
allow_deleted	If to include deleted records in the response.	False

filter_

The filter can either be a basic filter, consisting of 3 key-value pairs:

• field: the field to match against
• op: the operation used for matching, possible values: eq, neq, like, notlike, lt, gt, lte, gte, set, unset, in, notin
• value: match to this value, mutually exclusive with value_field
• value_field: match the field of this record, mutually exclusive with value

note

A value still needs to be specified when using the set or unset operation, even though it has no effect.

note

The field can map to other records. The following syntax is used to map to another record:

<own field>--<other record>.<join field>:<filter field>

or it can contain a collection of filters using the and or or key:

• and: every filter provided in the list must be True
• or: at least one filter provided in the list must be True

example

Filter resources which were created by either of the two identities, given their name. Be aware that multiple identities can share the same name (executions for example) and that thus this example might include more records than anticipated.

{
  "or": [
    {
      "field": "created_by--identity.id:name",
      "op": "eq",
      "value": "some-user"
    },
    {
      "field": "created_by--identity.id:name",
      "op": "eq",
      "value": "some-other-user"
    }
  ]
}

The previous example could also be rewritten using the in operation:

{
  {
    "field": "created_by--identity.id:name",
    "op": "in",
    "value": ["some-user", "some-other-user"]
  },
}

Reading

Via the User Interface

1. Enter the name or parts of the name of the record in the quick search bar.
2. Click on the record in the quick search results.
3. The record is opened in the main section.

Via the REST API

Send a GET request to

https://<your-workspace-name>.cloudomation.com/api/latest/<record-type>/<record-id>

You can also access resources by name:

Send a GET request to:

https://<your-workspace-name>.cloudomation.com/api/latest/<resource-type>/<resource-name>?by=name

note

See the records reference to learn about the different resources and activities

You can specify the fields you are interested in:

https://<your-workspace-name>.cloudomation.com/api/latest/<record-type>/<record-id>?fields=id,name,description

Via the Engine Flow API

Use the following method:

import flow_api

def handler(system: flow_api.System, this: flow_api.Execution, inputs: dict):
    system.<record-type>('name of the record').get('name of field to read')
    # for example:
    description = system.flow('my-flow').get('description')
    # you can read several fields at once:
    created_at, modified_at = system.flow('my-flow').get('created_at', 'modified_at')

Updating

Via the User Interface

1. Open the record you want to modify.
2. Change any field of the record.
3. Press the "save" button.

Via the REST API

Send a PATCH request to:

https://<your-workspace-name>.cloudomation.com/api/latest/<record-type>/<record-id>

The JSON payload should contain all fields you wish to update.

Via the Engine Flow API

Use the following method:

import flow_api

def handler(system: flow_api.System, this: flow_api.Execution, inputs: dict):
    system.user('<my-user-name>').save(description='This is me')

Deleting

Refer to Trash (deleted records) for information on how to move to trash, permanently delete and restore records.

Learn More

Records reference

Authentication

Git Integration