Deprecated

This component is deprecated. Use @advanced-rest-client/app instead.

---

The UI and logic for Advanced REST Client HTTP request actions.

This module contains a set of web components and libraries responsible for providing the UI and execution of actions in the Advanced REST Client application. An action is a runnable command that is executed, depending on the configuration, before or after the request. Actions can change data stored in ARC, like variables or cookies, based on the data in request or response.

The module replaces:

• the request-actions-panel component
• other ARC's local libraries in the application logic to process actions.

Installation

npm i @advanced-rest-client/arc-actions

Usage

ARC actions UI

The component has request and response properties that contains request and response actions definitions respectively.

Each time the user change an editor value the change event is dispatched from the panel. The event detail object contains the type property that indicates which array changed. Possible values are request and response.

Corresponding onchange setter is available.

render() {
  const {
    request = [],
    response = [],
    compatibility,
    outlined,
  } = this;
  return html`
  <arc-actions
    .request="${request}"
    .response="${response}"
    ?compatibility="${compatibility}"
    ?outlined="${outlined}"
    @actionchange="${this._actionsChange}"
  ></arc-actions>`;
}

_actionsChange(e) {
  const { type } = e.detail;
  const { target } = e;
  const list = type === 'request' ? target.request : target.response;
  this[key] = list;
}

The view can be controlled by setting selected property which is 0-based index of the selected tab. When a user change the selection of the tab the selectedchange event is dispatched. Corresponding onselectedchange setter is available.

Concept of an action

An action is a predefined logic that runs after initial conditions are met. Each action is executed in order, one-by-one (unless the sync property of the Action interface is set to false), in a context of request object, and when executing a response action also in context of the executed request and the response. Executed request is similar to the request but it is generated by the transport library with the actual sent message properties, which can be different that the ARC editor request.

The main object is the Condition. Each condition is can contains as many actions as needed. Actions are executed only when the condition is satisfied. The Condition reads the request or response data (depending on type and configuration) and check whether is passes given condition. For example it is possible to run a group of actions only when the response states equal 200. When the condition is not satisfied then the whole group is ignored.

An action added to the condition, depending on the context (the type, either the request or response) has different source configuration. The request has method source, but the response has status source type. Depending on this selection data are read from one or another. Note, the action's config.type and config.source.type and not the same. The config.type determines what kind of view to generate in the UI (source options), while the `config.source.type`` tells the actions runner from where to read the data from.

Actions do not perform the logic they are representing. They are using ARC DOM events system to communicate with the corresponding modules to execute the actual logic. In this sense, actions only prepare the configuration to the corresponding module and dispatch events defined in arc-events module.

Actions runnable

The actions are part of the ARC request object and located as request.actions object. The object contains optional request and response arrays with the list of conditions (action groups). The ActionsRunner class has processRequestActions() to execute request actions and processResponseActions() to execute actions in the context of the response.

The runner uses Jexl library to evaluate variables in actions definitions. Because Jexl is not ES modules friendly, a reference to it has to be provided in the constructor. The variables are read from ARC's variables model defined in arc-models library. The runner uses arc-events to communicate with the model to request the current environment. At the moment only the currently selected environment is used to evaluate the actions.

Action iterators

Sometimes an action needs to read a value from an array of response data. To enable the user to search for the specific data the ArcAction interface has a concept of an iterator. It is an additional configuration for the data reader of how to find a specific value in an array.

Consider the following response message:

{
  "items": [
    {
      "id": "1",
      "name": "John"
    },
    {
      "id": "2",
      "name": "Paul"
    }
  ]
}

It is possible to build the path to the specific array item by pointing to a specific index in the array like this:

items.1.id

This path would read value 2. But in a case where you cannot be sure whether the resulting array will have this specific order an iterator should be used.

To enable array search, (or an iterator) additional source configuration of the actions configuration is added.

{
  "source": {
    "type": "response",
    "source": "body",
    "path": "items.*.id",
    "iteratorEnabled": true,
    "iterator": {
      "operator": "equal",
      "condition": "Paul",
      "path": "name"
    },
  },
}

This configuration returns the id on an array item (array is declared as *). For each array entry the iterator configuration is executed to extract the data located under the iterator.path and compare it to the data defined in the condition. Finally, when the iterator finds the corresponding entry the rest of the main path is read to read the data.

Note, this behavior chanced in ARC 16. Before the main path was only pointing to the property inside found value by the iterator and the iterator.path was defining the full path to the value to compare.

Development

git clone https://github.com/advanced-rest-client/arc-actions
cd arc-actions
npm install

Running the demo locally

npm start

Running the tests

npm test