Difference between revisions of "External Data Source Integration"

From SmartWiki
Jump to: navigation, search
(Setting up a New Integration)
(Setting up a New Integration)
 
(7 intermediate revisions by 2 users not shown)
Line 8: Line 8:
 
# Go to '''Global Settings''' > '''Integrations''' tab > '''External Data Source Integration''' > Click the '''New External Data Source Integration''' button (looks like a plus sign).
 
# Go to '''Global Settings''' > '''Integrations''' tab > '''External Data Source Integration''' > Click the '''New External Data Source Integration''' button (looks like a plus sign).
 
# For '''Reference Name''', enter the name by which the integration will be referenced by the variable processor. For example, “chatbot”.
 
# For '''Reference Name''', enter the name by which the integration will be referenced by the variable processor. For example, “chatbot”.
# For '''Data Source URL''', enter the URL of the third-party data source from which we are pulling the external data.
+
# For '''Data Source URL''', enter the URL of the third-party data source (API) endpoint from which we are pulling the external data.
 
# Under '''Method''', select the desired HTTP method for the operation.
 
# Under '''Method''', select the desired HTTP method for the operation.
 
## To retrieve data from a server, select “GET”.
 
## To retrieve data from a server, select “GET”.
Line 16: Line 16:
 
# Under '''Format''', select the data format to be used in the HTTP call.
 
# Under '''Format''', select the data format to be used in the HTTP call.
 
# Under '''Header''', enter the HTTP headers to be sent in the request (Example: Content-Type, Authorization, etc). Each header pair must be delimited by a line break.
 
# Under '''Header''', enter the HTTP headers to be sent in the request (Example: Content-Type, Authorization, etc). Each header pair must be delimited by a line break.
# Under '''Values Template''', set up the instructions to the data source in either JSON or parameter value pair format.
+
# Under '''Values Template''', set up parameters or request body in either JSON or parameter value pair format.
 
# For '''Cache for''', enter how many hours the data should be cached for before pulling from the data source again. Set '''Cache for''' to “0” if you don’t want to use cached data.
 
# For '''Cache for''', enter how many hours the data should be cached for before pulling from the data source again. Set '''Cache for''' to “0” if you don’t want to use cached data.
  
 
==Header Example==
 
==Header Example==
For the '''Header''' field, enter the HTTP headers to be sent in the request. Each header pair must be delimited by a line break. For example, this is a sample header that could be used when properly filled out:
+
For the '''Header''' field, enter the HTTP headers to be sent in the request. Each header pair must be delimited by a line break. For example:
  
 
<pre>Content-Type: application/json
 
<pre>Content-Type: application/json
 
Authorization: Bearer xxxxxxxxx
 
Authorization: Bearer xxxxxxxxx
 
</pre>
 
</pre>
 
  
 
==Values Template Example: JSON Format==
 
==Values Template Example: JSON Format==
Line 48: Line 47:
  
 
* When a numeric values is required as the data value inside the JSON, wrap the variable name with the number symbol ( # ). For example, enter <code>"temperature":#temperature#</code> to resolve the variable name <code>"temperature"</code> as a numeric value. 
 
* When a numeric values is required as the data value inside the JSON, wrap the variable name with the number symbol ( # ). For example, enter <code>"temperature":#temperature#</code> to resolve the variable name <code>"temperature"</code> as a numeric value. 
* If the variable is a string type, the system will put double quotation marks ( " " ) around the value and escape all special character
+
* If the variable is a string type, the system will put double quotation marks ( " " ) around the value and escape special characters
 +
* The example provided above is based on OpenAI's Chat Completions API endpoint available at: https://platform.openai.com/docs/api-reference/chat
 +
* The accepted JSON Format varies depending on the API's requirements, defined by the Data Source URL field. Please consult the configured API's own documentation when structuring the JSON Object within the Values Template field.
  
 
==Values Template Example: Name Pairs==
 
==Values Template Example: Name Pairs==
Line 61: Line 62:
  
 
==Using the Variable Processor==
 
==Using the Variable Processor==
Once the previous integration has been set up, we can interact with the external data source by calling it through the variable processor. The variable processor uses semicolons ( ; ) as the default delimiter. However, the syntax can be modified to use other delimiters as well. To test this integration, do the following:
+
Once the previous integration has been set up, we can interact with the external data source by calling it through the variable processor. The variable processor uses semicolons ( ; ) as the default delimiter. However, the syntax can be modified to use other delimiters. To test this integration, do the following:
  
 
# Go to the desired UTA and open a record
 
# Go to the desired UTA and open a record
 
# Go to '''Tools''' > '''Configuration Mode''' > '''Variable Syntax Helper'''
 
# Go to '''Tools''' > '''Configuration Mode''' > '''Variable Syntax Helper'''
 
# In the '''Expressions''' input, enter a call to the integration using the syntax examples below
 
# In the '''Expressions''' input, enter a call to the integration using the syntax examples below
# Click '''Evaluate''' to ensure proper resolution of values
+
# Click '''Evaluate''' to ensure the request resolves as expected
  
 
===Example Syntax (Default Delimiter)===
 
===Example Syntax (Default Delimiter)===

Latest revision as of 14:16, 1 April 2024

Overview

This article is about how to set up an integration to pull data from an external source using the variable processor. This gives you the ability to pull data from external sources into SmartSimple on demand. This article will show you how to set up the integration and an explanation of the settings.

Configuration

Setting up a New Integration

To set up a new configuration, follow these steps:

  1. Go to Global Settings > Integrations tab > External Data Source Integration > Click the New External Data Source Integration button (looks like a plus sign).
  2. For Reference Name, enter the name by which the integration will be referenced by the variable processor. For example, “chatbot”.
  3. For Data Source URL, enter the URL of the third-party data source (API) endpoint from which we are pulling the external data.
  4. Under Method, select the desired HTTP method for the operation.
    1. To retrieve data from a server, select “GET”.
    2. To create new records, select “POST”.
    3. To replace an existing record with an updated version, select “PUT”.
    4. To remove data, select “DELETE”.
  5. Under Format, select the data format to be used in the HTTP call.
  6. Under Header, enter the HTTP headers to be sent in the request (Example: Content-Type, Authorization, etc). Each header pair must be delimited by a line break.
  7. Under Values Template, set up parameters or request body in either JSON or parameter value pair format.
  8. For Cache for, enter how many hours the data should be cached for before pulling from the data source again. Set Cache for to “0” if you don’t want to use cached data.

Header Example

For the Header field, enter the HTTP headers to be sent in the request. Each header pair must be delimited by a line break. For example:

Content-Type: application/json
Authorization: Bearer xxxxxxxxx

Values Template Example: JSON Format

In this example, the template is formatted as a JSON:

{
"model": "gpt-3.5-turbo",
"temperature":#temperature#,
"messages": [
  	{
    	"role": "system",
    	"content": "You are a helpful assistant."
  	},
  	{
    	"role": @thisrole@,
        "content": @content@
  	}
]
}

Note:

  • When a numeric values is required as the data value inside the JSON, wrap the variable name with the number symbol ( # ). For example, enter "temperature":#temperature# to resolve the variable name "temperature" as a numeric value. 
  • If the variable is a string type, the system will put double quotation marks ( " " ) around the value and escape special characters
  • The example provided above is based on OpenAI's Chat Completions API endpoint available at: https://platform.openai.com/docs/api-reference/chat
  • The accepted JSON Format varies depending on the API's requirements, defined by the Data Source URL field. Please consult the configured API's own documentation when structuring the JSON Object within the Values Template field.

Values Template Example: Name Pairs

In this example, the template is formatted with name pairs. Each name pair must be delimited by a line break.

role=@thisrole@
temperature=#temperature#
model=gpt-3.5-turbo
content=@content@


Using the Variable Processor

Once the previous integration has been set up, we can interact with the external data source by calling it through the variable processor. The variable processor uses semicolons ( ; ) as the default delimiter. However, the syntax can be modified to use other delimiters. To test this integration, do the following:

  1. Go to the desired UTA and open a record
  2. Go to Tools > Configuration Mode > Variable Syntax Helper
  3. In the Expressions input, enter a call to the integration using the syntax examples below
  4. Click Evaluate to ensure the request resolves as expected

Example Syntax (Default Delimiter)

In this example, “chatbot” is the Reference Name of our external integration. Note that we do not need to specify the delimiter because a semicolon is used by default.

Ticket-149530-1.png

Example Syntax (Custom Delimiter)

In this example, we can use a custom delimiter in the form of a double colon ( :: ) by passing the symbol as the second parameter in our call to the external data source.

Ticket-149530-2.png