Use a Procedure as a Resource

You can expose procedures that have manual triggers as a resource, known as Procedure as a Resource, or PaaF. This enables you to use the procedure 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-us.integrate.sugarapps.com/elements/api-v2/<resourceName>.  Using a procedure as a resource enables you to further remove logic from your applications and also provides the ability to more efficiently chain requests together.

PaaFs 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 PaaF 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, Sugar Integrate imposes a processing time limit. If the request reaches that limit, the response notifies you.

Set up a PaaF

To use a procedure as resource:

  1. Open the procedure template. On the Procedures page, hover over the Procedure Card, and then click Open.
  2. Click Edit.

    Edit formula

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

    • In API Method select the method used to call the procedure, such as GET, POST, PUT, PATCH, or DELETE.
    • In API URI enter the resource name of the procedure, such as /account-enhanced.
  5. Click Save.

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

Execute PaaFs

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

curl -X GET \
  https://api-us.integrate.sugarapps.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 Procedure Instance Card under the title.

Formula Instance ID

Note: Procedures used as a resource do not report step-end events. In practice, this means that any of executions using of a procedure as a resource using the V3 engine will not report steps or events, even if your procedure has debug logging enabled.

Access PaaF API Docs

To access the docs for the PaaF:

  1. On the Procedures page, hover over the Procedure Card, and then click API Docs.

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

Status Codes

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

  1. In the procedure, 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 procedures as a resource, and then access the results of the response within the context of the procedure.

To include a parameter in a procedure 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-us.integrate.sugarapps.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))