Flows Metadata & Filtering

Appmixer flows can contain custom metadata specific to your application. This is especially useful for filtering flows and displaying different flows for different use cases.

Setting Custom Metadata

Each flow can have assigned a custom metadata JSON object the customFields field. In the examples below, we show how to define custom metadata on a flow using each of the available Appmixer interfaces (REST API, Appmixer SDK).

Setting Custom Metadata using the REST API

Use the customFields object when creating new flows:

$ curl -XPOST "https://api.appmixer.com/flows" \
-H "Content-Type: application/json" \
-d '{ "flow": FLOW_DESCRIPTOR, "name": "My Flow #1", "customFields": { "category": "healthcare" } }'

... or when updating existing flows:

$ curl -XPUT "https://api.appmixer.com/flows/9089f275-f5a5-4796-ba23-365412c5666e" \
-H "Content-Type: application/json" \
-d '{ "customFields": { "category": "healthcare" } }'

Setting Custom Metadata using the Appmixer SDK

Create new flows with customFields:

appmixer.api.createFlow('myFlow', FLOW_DESCRIPTOR, {
    "customFields": { "category": "healthcare" }
});

... or update existing flows with:

appmixer.api.updateFlow('9089f275-f5a5-4796-ba23-365412c5666e', {
    "customFields": { "category": "healthcare" }
});

Search Flows Based on Custom Metadata

Now when you have flows with your own custom metadata defined, you can use filters to search for flows based on values of your metadata.

Filter Flows using the REST API

$ curl "https://api.appmixer.com/flows?filter=customFields.category:healthcare" \
-H "Authorization: Bearer [ACCESS_TOKEN]"

Moreover, you can use the following operators in your filter queries: !, ^, $, ~, >, <, $in. For example, to filter flows that do not fall into our "healthcare" category, we can use:

$ curl "https://api.appmixer.com/flows?filter=customFields.category:!healthcare" \
-H "Authorization: Bearer [ACCESS_TOKEN]"

Filter Flows using the Appmixer SDK

appmixer.api.getFlows({
    limit: 20,
    offset: 0,
    projection: "-thumbnail",
    sort: "mtime:-1",
    filter: "customFields.category:healthcare"
})

Appmixer UI SDK FlowManager with Custom Metadata

The main power of custom metadata is that you can display multiple FlowManager UI instances on your pages for different categories of flows. A typical example is to have a custom field "template" and split all flows in Appmixer to "template" flows and actual flow instances. You can achieve that by having two lists of flows in your UI displayed with the FlowManager UI widget, one for flow templates and one for actual flow runs. The flow templates would only display flows with "template:true" filter and the other list will display flows with "template:!true" filter. Based on where the user actually created the new flow, you would assign either template:true or template:false custom field to the flow object.

Filter Flows with FlowManager

Use the customFilter option when creating an instance of your flow manager. The FlowManager widget will then use this filter whenever requesting list of flows to display from the API:

const flowManagerTemplates = new appmixer.ui.FlowManager({
    el: '#your-flow-manager-templates-div',
    options: {
        customFilter: {
            'customFields.template': 'true'
        }
    }
});
flowManagerTemplates.open();

You can have another instance of FlowManager with non-template flows:

const flowManagerFlows = new appmixer.ui.FlowManager({
    el: '#your-flow-manager-flows-div',
    options: {
        customFilter: {
            'customFields.template': '!true'
        }
    }
});
flowManagerFlows.open();