Operation Library
The Operation Library, accessed on the Execution ribbon, is a catalog of external system operations available for integration with your model through interfaces and operations.
Each operation performs a specific action via a REST service call, with a defined URL, request message, and response/error messages. Related operations are grouped into interfaces, typically sharing the same server URL.
Interfaces represent a reference to an external system. Each interface has operations that represents an interaction that can be done with the system.
For example, in the image above, YH Finance is an an interface with one operation, Get Quotes, and NS is an interface with 10 operations.
Interfaces and operations may be imported from OpenAPI files or OData files, or created manually from API documentation.
OpenAPI and the Operation Library
The Operation Library is designed following the OpenAPI 3 specification. An interface is closely related to an OpenAPI definition and operations are closely related to paths.
The operation library dialog offers an Import OpenAPI option to directly import an OpenAPI v2/v3 or Swagger v2 JSON definition as a new interface. On import, paths get mapped as operations and defined data types are imported as well.
The following limitation exists when importing from OpenAPI:
-
If multiple servers are defined, only the first one is considered.
-
If multiple security definitions are defined, only the first one is considered.
-
Security defined by reference is not supported.
-
Only HTTP/HTTPS protocols are supported.
-
The data type file is not currently supported.
-
Imports and references to externally defined data type is not supported.
-
Some JSON Schema constraints are not imported for data types.
OData and the Operation Library
OData is a popular standard to expose persistent data from data sources and databases to a REST universe. The Import OData functionality allows to create an interface from an OData metadata XML file. Typically this metadata service is available under the https://service/$metadata/ URL of your data service.
When importing an OData metadata definition, an interface is created with operations for each selected entities to import with operations to get, find, create, update and delete the entity.
Once imported, the interface and operations can be renamed if desired. A dialog asks for the Server URL and security definition of your data service because that information is not carried in the metadata.
| Feel free to delete any generated operations that you would not use in your model. |
Interfaces
Interfaces have the following attributes.
Name |
A user label to identify this interface. This is for documentation purpose only. |
Description |
A user entered description of the interface. This is for documentation purpose only. |
Server URL |
The base URL of the REST server. Operations define their path based on this Server URL. The server URL can’t contain query parameters, these are defined at the operation level. |
Allow URL Override |
If this is checked, the Server URL is allowed to be changed at automation based on headers received when the service is called. This is required for SMART on FHIR applications. |
API Version |
A user entered information about the version of the REST API being used. This is for documentation purpose only. |
Security Type |
The required identity type. The next table gives more information on the different security types. |
Allow Provided Identity |
If this is checked, the identity used to access this interface is allowed to be provided at automation based on headers received when the service is called. This is required for SMART on FHIR applications. |
Authorization for a server can be configured with these types.
None |
The REST service does not require authorization. |
Http |
The REST service requires HTTP authentication that is defined as a Header with the format: |
Api Key |
The REST service requires an API key as a form of authorization. The In field represents the location where the API key will be sent (query, header, cookie). The name is the name of the query, header or cookie that will contain the API key. |
OAuth2 |
The REST service follows one of the OAUTH 2 flows. Flows currently supported are authorization code, client credentials, implicit and password. Based on the selected flow, the different URLs need to be entered. These URLs are typically provided by your service. The automation supports services with and without refresh tokens (therefore that field can be left blank if not supported by your service). |
OAuth |
The REST service follows the OAuth (v1) flow. This type should not be used since there are flaws in the OAuth v1 specification that prevents it from being consistently implemented across vendors. Note that our implementation is aligned with the Twitter implementation but there is no guarantee that it will properly work with other vendors. |
| Only the definition of the security is done in the Operation Library. The actual identity secrets used are later connected at deployment time. Your model does not contain secret information and identities are kept separate from your models. |
Operations
Each operation represents a REST call being made to the server. Operations have the following properties.
Name |
A user label to identify this operation. This is for documentation purpose only. |
Description |
A user entered description of the operation. This is for documentation purpose only. |
Method |
The REST verb used when communicating with the server. Supported are: GET, POST, PUT, DELETE, HEAD and PATCH. |
Path |
The REST endpoint path relative to the interface Server URL. The path should start with a |
Inputs |
Defines this operation input requirements. Those are the parameters that are sent to the REST endpoint. See the section on inputs for more detail on their mapping. |
Output |
Defines this operation output. This defines the response received from the REST endpoint. See the section on output for more detail on their mapping. |
Errors |
Defines this operation errors. Those are the potential error codes that are returned by the REST endpoint. See the section on errors for more detail on their mapping. |
Inputs
Input are later mapped from model data elements to be sent to the REST endpoint.
Name |
The parameter name of the input. Unless the In attribute is set to body, this value will be used to determine how the value is sent (ex: if In is header, this is the name of the header that is sent on the REST call). |
Type |
The data type of this input. |
In |
Offers different ways of sending this input parameter in the REST call:
|
Description |
A user entered description of the input parameter. This is for documentation purpose only. |
Required |
If this input parameter is required to be sent. |
Default Value |
A default value for this parameter. If a parameter is required and absent, the default value is sent. |
Output
A single output fpr a REST call can be defined. This output comes most likely from the body of the HTTP response but could also be taken from a Header.
Name |
The name of the output. If the output is taken from the body, this name could be anything that you will want to reuse in the output data mapping to reference the result of the operation. However, if the output is taken from a header, the name needs to be the name of the header from which the output value is read. |
Type |
The data type of the output. |
In |
Extraction location for the output. |
Body Content-Type |
How to parse the body when extracting the output from the body. If left blank, the response headers are considered to detect the Content-Type. |
Errors
Optionally, errors can be declared for REST calls that would return a non 2XX HTTP code.
Name |
A user defined label for this error. |
Type |
The data type of the error |
Error code |
The HTTP error code (404, 500, …) that matches this error. |
Body Content-Type |
How to parse the body of the error. If left blank, the response headers are considered to detect the Content-Type. |