OData

learn how to connect an odata service to engini, allowing real time integration of external business data into your automations connecting engini to odata enter your engini account at https //app engini io https //app engini io/ navigate to connections page by clicking on the connections on the left side bar or by clicking here https //app engini io/connections click on the “new integration” option located at the top bar choose “odata” option from available applications enter the following details in the “add connection” form there are five types of authorization in this guide, we will cover each of them basic authorization type connection name – a unique identifier for the connection within engini base url – enter the root url of your odata service authorization type – choose the method used to authenticate your connection to the odata service basic – simple authentication using a username and password common in internal or simpler odata services ssl certificate verification – choose whether to verify the ssl certificate of the server set this to true to enforce secure connection validation use false only in trusted test environments communication channel – choose how engini will communicate with your odata service cloud – default option use this when your odata service is accessible over the public internet opa – select this when your odata service is hosted on a private network and requires engini’s on prem agent (opa) to establish a secure connection behind a firewall advanced settings key enter the username provided by your odata service provider value enter the corresponding password for the username above save settings – click save to complete the connection setup bearer token authorization type connection name – a unique identifier for the connection within engini base url – enter the root url of your odata service authorization type – choose the method used to authenticate your connection to the odata service select bearer token from the dropdown list ssl certificate verification – choose whether to enforce ssl certificate validation set to true to ensure secure https communication set to false only if you’re connecting to development or self signed endpoint communication chanel – select how engini will access your service cloud – use only if your odata api is publicly accessible over the internet opa – select if your odata server resides on a private network and you want to connect via engini’s on prem agent (opa) advanced settings key – paste your bearer token here this token is usually obtained manually from your identity provider or authorization server and is used as is for authenticating requests value enter the corresponding password for the username above save settings – click save to complete the connection setup oauth 1 0 oauth 1 0 is an authentication protocol that allows secure access to apis without sharing user passwords connection name – a unique identifier for the connection within engini base url – provide the base odata endpoint you wish to connect to authorization type – select oauth 1 0 as the authorization method add authorization to – choose whether to add it to the request headers or to the request url signature method – choose the signature method required by your odata provider engini currently supports the following options hmac sha256 hmac sha512 consumer key – enter the oauth consumer key issued by your odata provider consumer secret – enter the corresponding consumer secret access token – provide the access token issued during the oauth 1 0 flow verifier – used in some flows (like oauth 1 0a) to confirm authorization include body hash set to true to include a hash of the request body in the signature (if required by the api) add empty parameters to signature – set to true if your provider expects all parameters (even empty ones) to be signed encode parameters into authorization header – determines whether the oauth parameters are placed in the http header or query string ssl certificate verification – set to true to verify the server’s ssl certificate set to false only in trusted internal environments communication channel – choose how engini should communicate with your service cloud – publicly accessible endpoints opa – for services behind a private network (requires engini on prem agent) advanced settings – optionally, you can add custom http headers or disable ssl checks save settings – click save to establish the connection oauth 2 0 oauth 2 0 is a modern authorization protocol that allows secure access to apis using access tokens instead of passwords connection name – a unique identifier for the connection within engini base url – provide the base odata endpoint you wish to connect to authorization type – select oauth 2 0 as the authorization method ssl certificate verification – choose whether to validate the ssl certificate of the remote service access token – engini will automatically retrieve this after you click signin (see below) no need to fill this manually redirect url – this is the url the authorization server will redirect to after the user authenticates you must register this url with your identity provider token url – the endpoint used to retrieve access and refresh tokens usually provided by your identity provider client id – the client/application id from your identify provider client secret – the secret associated with your client id scope – define your access scope requested from the provider sign in url – the authorization endpoint where the user is redirected to log in and approve access communication channel – choose how engini will connect to the service cloud – default option, for publicly accessible odata services opa – for internal/private services, using the on prem agent advanced settings check ssl certificate – toggle on to verify server certificate additional header – add any extra http headers required by the api signin – click signin to start the oauth authorization process this will open a browser window for login and consent save settings – after completing the sign in, click save to finalize the connection oauth 2 0 without sign in this option allows authentication using oauth 2 0 without a user login flow connection name – a unique identifier for the connection within engini base url – provide the base odata endpoint you wish to connect to authorization type – select oauth 2 0 without signin as the authorization method ssl certificate verification – choose whether to validate the ssl certificate of the service access token – this field will be populated automatically after token retrieval via the token url you don’t need to fill it manually refresh token – optional this is typically left blank for client credentials flows, as they often use short lived tokens without refresh capability token url – enter the full url of your identity provider’s token endpoint client id – the client/application id obtained from your identity provider client secret – the associated secret used to authenticate the client grant type – defaults to client credentials this is the only supported grant type for this flow communication channel – c hoose how engini should connect to your odata service cloud – for publicly accessible apis opa – if the service is hosted on a private network and requires the engini on prem agent advanced settings check ssl certificate – toggle this on to enable https certificate validation additional header – you can add custom http headers if your identity provider or api requires them save – after filling in the required fields, click save to finalize and activate the connection note after you’ve saved the connection, you can add additional objects and actions on the right side of the saved connection, you’ll see three dots click on the three dots and then click on “select database objects” a window will open displaying all available entities and actions, just like when you saved your connection from this window, select the new entities and actions you want to use activities create record this activity adds a new record to a selected odata entity, letting you insert data like customers, orders, products, or other custom entities defined in your service object type select the target entity where the new record should be created only entities that were selected during the “select database objects” step of the odata connection will appear here add fields select which fields to populate in the new record and provide their values click the empty field to the right of the dropdown to view a tooltip displaying all the available options for filling in the field you can populate the field in one of the following options static value – number / string when using strings, you need to surround them with single quotes (‘) property value from a previous activity (using the tooltip that opens when clicking on the field) expression – using functions and/or previous activity properties and/or static values (using the tooltip that opens when clicking on the field) repeat steps 1 3 for all the fields you want to populate create records batch this activity allows you to create multiple records for a specified odata entity in a single request object type this field defines the target entity for all records in the batch its options are limited to the entities you previously chose in the “select database objects” configuration for your odata connection date list provide an array of objects, where each object represents a record to be created each object in the array must contain the same structure, mapping the appropriate fields note maximum batch size is 1000 records per request add field define which fields will be populated in each record click the empty field to the right of the dropdown to view a tooltip displaying all the available options for filling in the field you can populate the field in one of the following options static value – number / string when using strings, you need to surround them with single quotes (‘) property value from a previous activity (using the tooltip that opens when clicking on the field) expression – using functions and/or previous activity properties and/or static values (using the tooltip that opens when clicking on the field) repeat steps 1 3 for all the fields you want to populate delete record this activity allows you to delete a specific record from an odata entity it’s used for removing existing data (e g , an old customer entry, a canceled order) object type select the entity from which you want to delete a record only entities selected during the “select database objects” step of your odata connection will appear here user name enter the value of the mandatory field used to identify the record to delete in the example shown, user name is the identifier for the people entity delete records batch this activity enables you to delete multiple records from a specified odata entity in a single batch request, enhancing efficiency when removing a large number of entries object type select the entity from which you want to delete a record only entities selected during the “select database objects” step of your odata connection will appear here data list provide an array of objects, where each object represents a record to delete maximum batch size is 1000 items per request icao code enter the value of a mandatory field used to identify the record to be deleted in the example shown, the icao code is the primary identifier for the airports entity execute action this activity allows you to execute custom actions defined within your odata service this is useful for triggering specific business logic or processes exposed by the odata service (e g , “reset data source”, “share trip”, “update last name” as seen in the “select database objects” image) action type this field selects the specific odata action to be executed its options are limited to the actions you previously chose in the “select database objects” configuration for your odata connection person user name – a mandatory field needed to execute the action last name – a mandatory field needed to execute the action note mandatory fields can vary depending on the action being performed in this case, the action is “update last name “ , and these two fields are required to complete it add field – define which fields will be populated in each record click on the empty field to the right of the drop down to be shown the tooltip with all the options you can use to fill the field you can populate the field in one of the following options static value – number / string when using strings, you need to surround them with single quotes (‘) property value from a previous activity (using the tooltip that opens when clicking on the field) expression – using functions and/or previous activity properties and/or static values (using the tooltip that opens when clicking on the field) repeat steps 1 3 for all the fields you want to populate get record this activity retrieves a single record from a specified odata entity based on its unique identifier it’s used for fetching specific data when you know the exact record you need object type – select the target entity from which a single record will be retrieved its options are limited to the entities you previously chose in the “select database objects” configuration for your odata connection icao code – provide the required value to identify the record to retrieve in this example, the icao code is the mandatory field for the airports entity output fields select one or multiple fields to include in the output these are the fields whose values will be available in downstream steps you can choose only the fields relevant to your use case to optimize performance and clarity get records this activity retrieves multiple records from a specified odata entity, supporting advanced queries like filtering, sorting, limiting results, and pagination for precise data retrieval object type – this field selects the target entity from which multiple records will be retrieved its options are limited to the entities you previously chose in the “select database objects” configuration for your odata connection output fields select one or multiple fields to include in the output these are the fields whose values will be available in downstream steps you can choose only the fields relevant to your use case to optimize performance and clarity add filters you can specify which records will be returned from the search results by utilizing the “add filter” button choose from the drop down the field you want to filter by select the condition you want the records to meet for the selected field click on the field to show the tooltip with all the options you can choose you can populate the field in one of the following options static value – number / string when using strings, you need to surround them with single quotes (‘) property value from a previous activity (using the tooltip that opens when clicking on the field) expression – using functions and/or previous activity properties and/or static values (using the tooltip that opens when clicking on the field) repeat steps 1 3 for all the fields you want to populate add sorting specify how the retrieved records should be ordered you can sort in ascending or descending order click on the “add sorting” button choose from the drop down the field you want to sort by choose the sorting option descending or ascending you can do a multi sort by choosing to sort more than one field use the arrows on the right to select the field that will be used as the primary sort, secondary, etc top n you can specify how many records with the same value you want to get click on ‘top n’ and enter the maximum number of values you want to retrieve for example – if you set top n = 1 , a single record will be returned instead of an array if no record is found, the action will fail, allowing you to implement an if condition within the workflow this can be useful for processes where the existence of a record determines the next steps in the workflow offset this field specifies the number of records to skip from the beginning of the result set before retrieving the rest it is commonly used for pagination in conjunction with top n for example if you set offset = 2 and top n = 3, three records will be returned starting from the second record will be returned if no record is found, the action will fail, allowing you to implement an if condition within the workflow this can be useful for processes where the existence of a record determines the next steps in the workflow get records batch this activity allows you to retrieve multiple specific records from an odata entity in a single batch request unlike “get records” which queries based on filters, this action fetches records based on a provided list of unique identifiers, making it efficient for retrieving known sets of records in bulk object type – this field selects the target entity from which records will be retrieved in batch its options are limited to the entities you previously chose in the “select database objects” configuration for your odata connection data list this field accepts an array of objects, where each object typically contains the unique identifier of a record to be retrieved icao code specify the icao code field that engini should use to match and retrieve each record in the batch in this example, icao code is the mandatory field of the airports entity initialize object array this activity initializes a new, empty object array and assigns it to a specified variable it’s typically used at the beginning of a process where you intend to collect multiple objects (e g , odata records) into a single array for later processing, such as batch operations or data manipulation variable name – this field defines the name of the new variable that will store the object array object item type – this field specifies the expected structure or schema of the individual objects that will be stored within the array select the type of object that this variable will contain this determines the structure and available fields for each item in the list add fields – by clicking the “add field” button, you can choose how to fill in the fields for the array you can add one field to the activity or more fields to the activity definitions, up to the number of fields you have in the selected object the fields vary depending on the selected object click on the empty field to the right of the drop down to be shown the tooltip with all the options you can use to fill the field you can populate the field in one of the following options static value – number / string when using strings, you need to surround them with single quotes (‘) property value from a previous activity (using the tooltip that opens when clicking on the field) expression – using functions and/or previous activity properties and/or static values (using the tooltip that opens when clicking on the field) repeat steps 1 3 for all the fields you want to populate append to object array this action adds a new object to an existing object array variable that was initialized earlier in the workflow variable – select the array you initialized in the previous steps after selecting the variable, the “add field” option becomes available add field – by clicking the “add field” button, you can choose how to fill in the various fields in the records you are creating you can add one field to the activity or more fields to the activity definitions, up to the number of fields you have in the selected object the fields vary depending on the selected object choose from the drop down the field you want to fill click on the empty field to the right of the drop down to be shown the tooltip with all the options you can use to fill the field you can populate the field in one of the following options static value – number / string when using strings, you need to surround them with single quotes (‘) property value from a previous activity (using the tooltip that opens when clicking on the field) expression – using functions and/or previous activity properties and/or static values (using the tooltip that opens when clicking on the field) repeat steps 1 3 for all the fields you want to populate map object array this action transforms a list of objects (an array) from one structure to another it’s especially useful when you retrieve data from odata in one format and need to convert it to a different structure for use in subsequent actions or to send to another system data list – this field specifies the input array of objects that you wish to transform object name – select the type of object that each item in the list represents this defines the structure and available fields for each item during the mapping process add fields by clicking the “add field” button, you can choose how to fill in the various fields in the object you are mapping you can add one field to the activity or more fields to the activity definitions, up to the number of fields you have in the selected object the fields vary depending on the selected object click add field to insert a new mapping row in the dropdown, choose the field in the odata entity in the adjacent input, provide the expression or reference for the value update record this action modifies an existing record within a specified odata entity it’s used for changing specific fields of an existing data entry (e g , updating a customer’s address, changing an order status) object type – this field selects the target entity where an existing record will be updated its options are limited to the entities you previously chose in the “select database objects” configuration for your odata connection primary key field (e g , icao code) enter the value of the primary key that uniquely identifies the record update in this example, icao code is the mandatory field for the airports entity add fields define the fields you want to update and their new values click add field to add a new field value pair in the choose field dropdown, select the column to update in the adjacent input, provide the new value or expression repeat for each field you wish to modify click the trash icon to remove any unnecessary fields update records batch this action allows you to modify multiple existing records within a specified odata entity in a single batch request this is highly efficient for performing bulk updates to your data object type this field selects the target entity where all records in the batch will be updated its options are limited to the entities you previously chose in the “select database objects” configuration for your odata connection data list this field accepts an array of objects, where each object represents a record to be updated each object must include the unique identifier (key) of the record to be updated, along with the properties and their new values mandatory field (e g , icao code) enter the value of the primary field that uniquely identifies the record update in this example, icao code is the mandatory for the airports entity add field define the fields you want to update and their new values click add field to add a new field value pair in the choose field dropdown, select the column to update in the adjacent input, provide the new value or expression repeat for each field you wish to modify click the trash icon to remove any unnecessary fields