Use a Flow as a Resource

You can expose flows that have manual triggers as a resource, known as Flow as a Resource, or FaaR. This enables you to use the flow as an asynchronous API request. After you update a formula to be used as a resource, you can make API requests to it at https://api.cloud-elements.com/elements/api-v2//<resourceName>. Using a flow as a resource enables you to remove logic from your applications further and also provides the ability to more efficiently chain requests together.

FaaRs enable you to take APIs that require multiple operations to operate — operations that might be simple in other systems  — and wrap them in a single request. In this case, the FaaR acts as an authoritative resource that performs multi-step processes under the hood.

The API requests are synchronous, and so a response is required for further processing. To maintain efficiency, Axway AMPLIFY imposes a processing time limit. If the request reaches that limit, the response notifies you.

Set up a FaaR

To use a flow as a resource:

  1. Open the flow template. On the Flows page, hover over the Flow Card, and then click Open.
  2. Click Edit.
  3. Click Show Advanced.
  4. In the Execute Flow via API (BETA) section, update the API Method and API URI.
    • In API Method, select the method used to call the flow, such as GET, POST, PUT, PATCH, or DELETE.
    • In API URI, enter the resource name of the flow, such as /account-enhanced.
  5. Click Save.

After you create a FaaR, you can start making requests or take a look at the API docs, where you can also test your FaaR.

Execute FaaRs

To make an API request to the FaaR, include the flow instance (elements-formula-instance-id) in the header in addition to the usual User and Organization (no need to include an element token). For example:

curl -X GET \
  https://api.cloud-elements.com/elements/api-v2/formula1 \
  -H 'authorization: User <USER_SECRET>, Organization <ORGANIZATION_SECRET>' \
  -H 'elements-formula-instance-id: 28683' \

You can find the elements-formula-instance-id on a Flow Instance Card under the title.

Access FaaR API Docs

To access the docs for the FaaR:

  1. On the Flows page, hover over the Flow Card, and then click API Docs.
  2. On the API Docs page, click Try it Out.
  3. In Elements-Formula-Instance-Id enter a Flow Instance ID, and then execute the API call.

Status Codes

When you create a Flow as a Resource, you can specify status codes and descriptions. To include a status code and result in response to a FaaR request:

  1. In the flow, add a JS Script step as the final step.
  2. Include a script like the following in the step:

    done({
      statusCode: xxx
      result: {
        label: 'message'
      }
    })
  3. Save the step.

Property Description
statusCode The status code that you want to return in the response, such as 200, 401, or 502. The value must be a valid status code.
result The body of the response which can be anything related to the status code, such as an array of objects, a single object, or text. The example above includes an array containing a key-value pair with a label and a message.

Work with Parameters

You can pass parameters into flows as a resource, and then access the results of the response within the context of the flow.

To include a parameter in a flow as a resource:

  1. When you make the request, pass the parameter. An example cURL request with a query parameter to the resource called formula1, your endpoint would be:

    curl -X GET \
      https://api.cloud-elements.com/elements/api-v2/formula1?<queryParameter> \
      -H 'authorization: User <USER_SECRET>, Organization <ORGANIZATION_SECRET>' \
      -H 'elements-formula-instance-id: 28683' \
  2. Access data is returned in response to the request by using a script step. The data is available through trigger.args.request.query. An example script that passes query data containing an email address to the console would be:

    var queryObject = trigger.args.request.query;
    
    function getThatEmailAddress(emailAddressObject){
        console.log(emailAddressObject['email']);
    }
    
    done(getThatEmailAddress(queryObject))

Related Links