Skip to content

Service Integration

A Service Integration Business Object connects the app to an external service: a mail server, an HTTP API described by an OpenAPI schema, or a SOAP service described by a WSDL. In code, each one is reached as This.<IntegrationName>, and what it offers depends on its kind.

Availability: Server

This.<IntegrationName>

Service Integrations are not grouped under a $ namespace: they are reached directly as This.<IntegrationName>. They exist only in server-side code; client-side and shared code cannot reference them.

KindWhat This.<IntegrationName> offers
MailsendMail() and sendMails(). Only when the integration has a credential set.
OpenAPIOne function per HTTP method, serverUrls, getBaseUrl() and the schema’s types. Only when the integration has a schema.
SOAPOne function per WSDL operation, serverUrls, getBaseUrl() and the WSDL’s types. Only when the integration has a WSDL.
GraphQL, SAPNot available yet: Lowgile does not compile these kinds.
  • Requests go to getBaseUrl().
  • If the integration’s authentication is “Bearer token” or “Basic”, Lowgile evaluates its authentication expression for each request and sends the result as the authorization header. This header replaces an authorization header you pass yourself. For OpenAPI integrations without authentication, an authorization header you pass in lowercase is dropped.
  • OpenAPI only: a request that passes baseUrl in its options goes to that URL instead. Lowgile sends accept: application/json unless you pass another accept header.
  • OpenAPI only: if the integration needs a CSRF token, put(), post(), del() and patch() first fetch one with a GET request to the base URL and send it, with the cookies of that response, along with the request.
sendMail(mail: MailObject): Promise<void>

Mail integrations: sends one mail through the mail server configured in the integration’s credential.

ParameterTypeDescription
mailMailObjectThe mail to send.

Returns: Promise<void> · Availability: Server

If from is not set, the credential’s default sender is used. If the credential has sending to mock recipients turned on, the mail goes to the mock recipient addresses instead, without cc and bcc, and its text starts with a hint naming the real recipients.

Note

At runtime, the returned promise resolves to nodemailer’s send result for the mail, not to undefined.

sendMails(mails: MailObject[]): Promise<void>

Mail integrations: sends several mails over one connection to the mail server, in parallel. The promise rejects if any mail fails. Sender and mock recipients are handled as for sendMail().

ParameterTypeDescription
mailsMailObject[]The mails to send.

Returns: Promise<void> · Availability: Server

Note

At runtime, the returned promise resolves to an array of nodemailer send results, one per mail, not to undefined.

get: Client<paths>['GET']

OpenAPI integrations: sends a GET request to one of the schema’s paths. This and the following functions are the request methods of an openapi-fetch client (openapi-fetch ^0.12.2), typed from the integration’s schema: the path, its parameters and the request body are checked against the schema.

Returns: Promise of { data, error, response }: data on success, error with the parsed error body otherwise · Availability: Server

const { data, error } = await This.PetStore.get('/pets/{petId}', {
params: { path: { petId: 42 } },
})
put: Client<paths>['PUT']

OpenAPI integrations: sends a PUT request to one of the schema’s paths, like get().

Returns: Promise of { data, error, response } · Availability: Server

post: Client<paths>['POST']

OpenAPI integrations: sends a POST request to one of the schema’s paths, like get().

Returns: Promise of { data, error, response } · Availability: Server

del: Client<paths>['DELETE']

OpenAPI integrations: sends a DELETE request to one of the schema’s paths, like get().

Returns: Promise of { data, error, response } · Availability: Server

patch: Client<paths>['PATCH']

OpenAPI integrations: sends a PATCH request to one of the schema’s paths, like get().

Returns: Promise of { data, error, response } · Availability: Server

options: Client<paths>['OPTIONS']

OpenAPI integrations: sends an OPTIONS request to one of the schema’s paths, like get().

Returns: Promise of { data, error, response } · Availability: Server

head: Client<paths>['HEAD']

OpenAPI integrations: sends a HEAD request to one of the schema’s paths, like get().

Returns: Promise of { data, error, response } · Availability: Server

trace: Client<paths>['TRACE']

OpenAPI integrations: sends a TRACE request to one of the schema’s paths, like get().

Returns: Promise of { data, error, response } · Availability: Server

<operation>: (input: <InputType>, options?: Sys.Soap.SoapRequestOptions) => Promise<Sys.Soap.SoapCallResult<<OutputType>>>

SOAP integrations: calls one WSDL operation. There is one function per operation, named after it; characters other than letters, digits, _ and $ become _, and a name that does not start with a letter, _ or $ gets a leading _. <InputType> and <OutputType> are the operation’s message types, generated from the WSDL.

ParameterTypeDescription
input<InputType>The request element sent in the SOAP body.
optionsSys.Soap.SoapRequestOptionsExtra headers, a SOAP header, or a custom fetch.

SoapRequestOptions fields

FieldTypeRequiredDescription
headersRecord<string, string>noAdditional HTTP headers.
soapHeaderXmlstringnoRaw XML placed inside soap:Header.
fetchtypeof fetchnoThe fetch function to send the request with.

Returns: Promise<Sys.Soap.SoapCallResult<<OutputType>>> · Availability: Server

A SOAP fault, an HTTP error status or an invalid response does not reject the promise: it is returned in the result’s error. Network errors reject it.

getBaseUrl: () => string

OpenAPI and SOAP integrations: returns the URL requests are sent to. This is the integration’s base URL expression, evaluated on each call, or the first entry of serverUrls when no expression is set.

Returns: string · Availability: Server

serverUrls: string[]

OpenAPI and SOAP integrations: the server URLs listed in the OpenAPI schema’s servers, or the endpoint addresses in the WSDL.

Type: string[] · Availability: Server

type MailObject = SendMailOptions

The mail passed to sendMail() and sendMails(): nodemailer’s SendMailOptions (nodemailer ^8.0.1), with fields such as from, to, cc, bcc, subject, text, html and attachments. See the nodemailer message options.

Availability: Server

interface Sys.Soap.SoapCallResult<T>

The result of a SOAP operation.

FieldTypeRequiredDescription
dataTnoThe response element, when the call succeeded.
errorSoapFaultno{ code: string, message: string, detail?: unknown }, for a SOAP fault, an HTTP error status or an invalid response.
requestRequestyesThe HTTP request that was sent.
responseResponseyesThe HTTP response.
requestXmlstringyesThe SOAP envelope that was sent.
responseXmlstringyesThe response body.

Availability: Server

type <IntegrationName>.<TypeName>

OpenAPI integrations: each schema in the OpenAPI schema’s components.schemas becomes a type This.<IntegrationName>.<SchemaName>. Dashes in a schema name become _, and dots create nested namespaces, so order.line-item becomes This.<IntegrationName>.order.line_item.

SOAP integrations: each type defined in the WSDL becomes a type This.<IntegrationName>.<TypeName>.

Availability: Server