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.

Object Templates and Custom Objects

Refer to the dedicated flow_api methods for information on how to access and manipulate object templates and custom objects with the flow_api.

Record Metadata

You can associate any data, that can be stored in a valid json format, to any Cloudomation Engine record.

example

The following example shows how to create, modify, access, and delete metadata on a record. In this example the metadata will belong to the execution created by this script, but you can assign metadata to any record you like.

import flow_api

def handler(system: flow_api.System, this: flow_api.Execution, inputs: dict):
    # add metadata with key 'environment' and data='test' to this execution
    # get metadata of this this execution and write it into output value
    this.add_record_metadata(key='environment', data='test')
    output_value1 = [metadata.get_dict('key', 'data') for metadata in this.record_metadata_list()]
    this.set_output(output_value1=output_value1)
    
    # change metadata with key 'environment' and set data to 'prod'
    # add metadata with key 'about' and a json object as data to this execution
    # get metadata of this this execution and write it into output value
    this.metadata('environment').save(data='prod', record_id=this.get('id'))
    this.add_record_metadata(key='about', data={'author': 'my-user', 'initial_created_at': '2000-01-01T12:00:00'})
    output_value2 = [metadata.get_dict('key', 'data') for metadata in this.record_metadata_list()]
    this.set_output(output_value2=output_value2)
    
    # delete metadata with key 'environment'
    # get metadata of this this execution and write it into output value
    this.metadata('environment').delete(permanently=True)
    output_value3 = [metadata.get_dict('key', 'data') for metadata in this.record_metadata_list()]
    this.set_output(output_value3=output_value3)

    return this.success('all done')

The script logs the metadata in the output value of the execution, first after adding a metadata, second after editing the metadata and adding a new metadata, and finally, after deleting one of the metadata:

output_value1:
  - key: environment
    data: test
output_value2:
  - key: about
    data:
      author: my-user
      initial_created_at: '2000-01-01T12:00:00'
  - key: environment
    data: prod
output_value3:
  - key: about
    data:
      author: my-user
      initial_created_at: '2000-01-01T12:00:00'

Learn More

Records reference

Authentication

Git Integration