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
How to reach it
Section titled “How to reach it”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.
| Kind | What This.<IntegrationName> offers |
|---|---|
sendMail() and sendMails(). Only when the integration has a credential set. | |
| OpenAPI | One function per HTTP method, serverUrls, getBaseUrl() and the schema’s types. Only when the integration has a schema. |
| SOAP | One function per WSDL operation, serverUrls, getBaseUrl() and the WSDL’s types. Only when the integration has a WSDL. |
| GraphQL, SAP | Not available yet: Lowgile does not compile these kinds. |
Requests of OpenAPI and SOAP integrations
Section titled “Requests of OpenAPI and SOAP integrations”- 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
authorizationheader. This header replaces anauthorizationheader you pass yourself. For OpenAPI integrations without authentication, anauthorizationheader you pass in lowercase is dropped. - OpenAPI only: a request that passes
baseUrlin its options goes to that URL instead. Lowgile sendsaccept: application/jsonunless you pass anotheracceptheader. - OpenAPI only: if the integration needs a CSRF token,
put(),post(),del()andpatch()first fetch one with a GET request to the base URL and send it, with the cookies of that response, along with the request.
Functions
Section titled “Functions”sendMail()
Section titled “sendMail()”sendMail(mail: MailObject): Promise<void>Mail integrations: sends one mail through the mail server configured in the integration’s credential.
| Parameter | Type | Description |
|---|---|---|
mail | MailObject | The 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()
Section titled “sendMails()”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().
| Parameter | Type | Description |
|---|---|---|
mails | MailObject[] | 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()
Section titled “post()”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()
Section titled “patch()”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()
Section titled “options()”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()
Section titled “head()”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()
Section titled “trace()”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>()
Section titled “<operation>()”<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.
| Parameter | Type | Description |
|---|---|---|
input | <InputType> | The request element sent in the SOAP body. |
options | Sys.Soap.SoapRequestOptions | Extra headers, a SOAP header, or a custom fetch. |
SoapRequestOptions fields
| Field | Type | Required | Description |
|---|---|---|---|
headers | Record<string, string> | no | Additional HTTP headers. |
soapHeaderXml | string | no | Raw XML placed inside soap:Header. |
fetch | typeof fetch | no | The 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()
Section titled “getBaseUrl()”getBaseUrl: () => stringOpenAPI 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
Properties
Section titled “Properties”serverUrls
Section titled “serverUrls”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
MailObject
Section titled “MailObject”type MailObject = SendMailOptionsThe 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
SoapCallResult
Section titled “SoapCallResult”interface Sys.Soap.SoapCallResult<T>The result of a SOAP operation.
| Field | Type | Required | Description |
|---|---|---|---|
data | T | no | The response element, when the call succeeded. |
error | SoapFault | no | { code: string, message: string, detail?: unknown }, for a SOAP fault, an HTTP error status or an invalid response. |
request | Request | yes | The HTTP request that was sent. |
response | Response | yes | The HTTP response. |
requestXml | string | yes | The SOAP envelope that was sent. |
responseXml | string | yes | The response body. |
Availability: Server
Generated types
Section titled “Generated types”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