SAP Cloud Platform Open Connectors

Use a Formula as a Resource

You can expose formulas that have manual triggers as a resource, known as Formula as a Resource, or FaaR. This enables you to use the formula as a synchronous 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 formula as a resource enables you to further remove logic from your applications and also provides the ability to more efficiently chain requests together.

FaaRs enable you to take APIs that require multiple operations to perform an operation — operations that might be simple in other systems  — and wrap them in a single request. In this case, the FaaR acts as a canonical 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, Cloud Elements imposes a processing time limit. If the request reaches that limit, the response notifies you.

Set up a FaaR

To use a formula as resource:

  1. Open the formula template. On the Formulas page, hover over the Formula Card, and then click Open.
  2. Click Edit.

    Edit

  3. Click Show Advanced.
  4. In the Execute Formula via API (BETA) section, update the API Method and API URI.

    • In API Method select the method used to call the formula, such as GET, POST, PUT, PATCH, or DELETE.
    • In API URI enter the resource name of the formula, 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 formula 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 Formula Instance Card under the title.

Formula Instance ID

Access FaaR API Docs

To access the docs for the FaaR:

  1. On the Formulas page, hover over the Formula Card, and then click API Docs.

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

Status Codes

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

  1. In the formula, 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.

PropertyDescription
statusCodeThe status code that you want to return in the response, such as 200, 401, or 502. The value must be a valid status code.
resultThe 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 formulas as a resource, and then access the results of the response within the context of the formula.

To include a parameter in a formula 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 returned in the 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))