Skip to main content

Services

A service is an HTTP endpoint that the automator exposes to the outside world. Where a webhook receives events that an external system pushes to the automator, a service publishes an endpoint of your own: a web form for people, or an API for other systems. You control the response.

Services are configured in the Services tab. A service has one of three service types:

  • HTML: serves a web page on GET and processes a submitted form on POST. The page and the result are rendered from templates, linked to the service as GET template and POST template.
  • JSON: an API endpoint that accepts and returns JSON.
  • SOAP: a SOAP web service, described by the WSDL that you configure on the service.

Linking a service to a package​

A service is linked to a package with a Service GET or Service POST event. The package script runs before the response is produced:

  • For an HTML service, the script prepares data for the template by assigning global variables. On POST, the submitted form data is available in source.body.
  • For JSON and SOAP services, the script builds the response itself. The result variable name and status variable name fields of the service tell the automator which global variables hold the response body and the HTTP status code.

An HTML service without a linked package serves its GET template as-is, which is a simple way to publish a static page.

Service URLs​

The Service URLs section at the bottom of the service form shows the URLs of the service once you select an account. The account becomes the default account of the package execution, as for every trigger.

A service can be called by its UUID or by its name, and with two kinds of URLs: the URLs starting with /service/ and the API URLs starting with /service-api/. The /service/ URLs only accept GET and POST requests.

API URLs​

The API URLs of a service are meant for APIs. They have this format:

https://<automator host>/service-api/<profile>/<environment>/<account>/<service type>/<service>/<subpath>

An API URL differs from a /service/ URL in two ways:

  • HTTP methods: it accepts GET, QUERY, POST, PUT, PATCH and DELETE requests. GET and QUERY requests trigger the Service GET event, the other methods the Service POST event. The method is available in lowercase in source.params.http_request_method, for example "patch".
  • Subpath: the URL can be extended with a path of your own, which is available in source.params["0"]. Without a subpath, source.params["0"] is not set.

This makes it possible to implement a REST-style API with a single service. For example, for this request:

PATCH https://<automator host>/service-api/acme/production/erp/json/orders/42/lines

The package of the orders service receives:

log(source.params.http_request_method); // => patch
log(source.params["0"]); // => 42/lines

Authentication​

A service can be open (no authentication), or protected with HTTP basic authentication, OAuth 2.0 client credentials, or single sign-on with SAML 2.0.

See also​