Flows Metadata & Filtering

Appmixer flows can contain custom metadata specific to your application. This is especially useful for filtering flows and displaying different Flow Managers for different kinds of flows.

Setting Custom Metadata

Each flow can have assigned a custom metadata object. This metadata object is called customFields throughout the documentation and can be any JSON object. 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 the 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 list 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 flows with "template:!true" filter. Now 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();