...
For example, bellow is a sample of the connector properties.
| Expand | ||
|---|---|---|
| ||
| Expand | ||
| ||
|
| Info |
|---|
The options vary based on the connector type. The connector required options should be properly described in your 3rd party system documentation (it`s a generic remote access) |
MAPPING
The mapping elements depend on the document that requires to be synchronized in the Boxalino ecosystem. We expect our clients to work with headless CMS / 3rd party environments for their content sync.
The mapping exposes the Boxalino Data Structure for the requested document (ex: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/252280968/doc%2Bcontent ).
For each property, as an integrator, you have to map the connector`s output path (wildcards [*] allowed):
a) for the properties returned as “string”/single value: only one mapping is allowed (ex: id, type, creation, description, etc)
b) for the properties returned as “array” ([]) or “objects”({}), set a list with index property name (output)=> mapping path (input) :
the
outputis the explicit type (ex: for tags, the tagging source can be tags or default) or exposed property namethe
inputis the mapping logic (ex: all product IDs from data.product_ids[*].id are set as product_ids in localized_numeric_attributes)
Check bellow a sample for a prismic integration following the designed blog logic in our public repository:
The query content must be a list of filters and it should be escaped (copy-paste each [] filter into an escape/unescape online tool) Review this sample from Boxalino`s public Prismic repository:
|
| Expand | ||||
|---|---|---|---|---|
| ||||
The fields and filters must be escaped (copy-paste the graphiQL section into an escape/unescape online tool)
| ||||
| Info |
...
| Expand | ||
|---|---|---|
| ||
|
| Info |
|---|
The options vary based on the connector type. The connector required options should be properly described in your 3rd party system documentation (it`s a generic remote access) |
MAPPING
The mapping elements depend on the document that requires to be synchronized in the Boxalino ecosystem. We expect our clients to work with headless CMS / 3rd party environments for their content sync.
The mapping exposes the Boxalino Data Structure for the requested document (ex: https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/252280968/doc%2Bcontent ).
For each property, as an integrator, you have to map the connector`s output path (wildcards [*] allowed):
a) for the properties returned as “string”/single value: only one mapping is allowed (ex: id, type, creation, description, etc)
b) for the properties returned as “array” ([]) or “objects”({}), set a list with index property name (output)=> mapping path (input) :
the
outputis the explicit type (ex: for tags, the tagging source can be tags or default) or exposed property namethe
inputis the mapping logic (ex: all product IDs from data.product_ids[*].id are set as product_ids in localized_numeric_attributes)
Check bellow a sample for various integrations following the designed blog logic in our public repository:
| Expand | ||
|---|---|---|
| ||
|
| Expand | ||
|---|---|---|
| ||
Warning : the mapping fields must exist in the connector options ~fields~ property.
|
| Info |
|---|
At Boxalino, we try to map the way our client expects for a headless integration to work. For this reason, if your connector integration libraries allows for content to be accessed as HTML or text (ex: data.content) - this is as well possible.
|
The connector response returns the requested content (results) in the following:
| Expand | ||
|---|---|---|
| ||
|
| Expand | ||
|---|---|---|
| ||
|
LANGUAGES
This must be declared in order to map the exported language (ex: “de”) with your connector export value (ex:”en-de”).
| Code Block |
|---|
"languages": {
"de": "en-de",
"fr": "fr-ch"
} |
AVAILABLE SERVICES
In order to allow our integrators to validate that the existing data available in the 3rd party systems is properly exported, a few helper services are available:
TEST REQUEST
Use a simple TEST request in order to validate that the connection to your configured endpoint (connector property) is valid.
| Code Block |
|---|
curl https://boxalino-di-transformer-krceabfwya-ew.a.run.app/test \
-X POST \
-d "[{\"connector\":{\"type\":\"prismic\",\"options\":{\"url\":\"https:\/\/rtux-integration.cdn.prismic.io\/api\/v2\/\",\"access_token\":\"MC5ZSkU4SnhBQUFDSUFXSXZR.77-9QO-_vWR577-977-9HO-_ve-_ve-_vXPvv73vv71LeO-_vUNi77-9Ii3vv73vv73vv71sC2Xvv71A77-9IA\",\"query\":[\"[at(document.type, \\\"category\\\")]\"]}},\"document\":{},\"mapping\":{},\"languages\":{}},{\"connector\":{\"type\":\"prismic\",\"options\":{\"url\":\"https:\/\/rtux-integration.cdn.prismic.io\/api\/v2\/\",\"access_token\":\"MC5ZSkU4SnhBQUFDSUFXSXZR.77-9QO-_vWR577-977-9HO-_ve-_ve-_vXPvv73vv71LeO-_vUNi77-9Ii3vv73vv73vv71sC2Xvv71A77-9IA\",\"query\":[\"[at(document.type, \\\"blog\\\")]\"]}},\"document\":{},\"mapping\":{},\"languages\":{}},{\r\n \"connector\": {\r\n \"type\": \"graphql\",\r\n \"options\": {\r\n \"endpoint\": \"https:\/\/api-eu-central-1.graphcms.com\/v2\/ckll4a83ni7og01yzfr3k9yc4\/master\",\r\n \"token\": \"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImdjbXMtbWFpbi1wcm9kdWN0aW9uIn0.eyJ2ZXJzaW9uIjozLCJpYXQiOjE2MjI1NjIzMzMsImF1ZCI6WyJodHRwczovL2FwaS1ldS1jZW50cmFsLTEuZ3JhcGhjbXMuY29tL3YyL2NrbGw0YTgzbmk3b2cwMXl6ZnIzazl5YzQvbWFzdGVyIiwiaHR0cHM6Ly9tYW5hZ2VtZW50LW5leHQuZ3JhcGhjbXMuY29tIl0sImlzcyI6Imh0dHBzOi8vbWFuYWdlbWVudC5ncmFwaGNtcy5jb20vIiwic3ViIjoiZjZlMTcyNGYtOTI2NS00OTFjLWEwMzktYzFkNGI2ZDExZDA5IiwianRpIjoiY2twZTdweDVoZGR2bzAxejU1NjNwZjc1cCJ9.MjYP8I7OvwyOkiHiB22LPwOfRzEt_ilvp6jHTVufkQEs6UTxJeuOEDvcojbMAgiEa3lStbc3mOVDezOQhMoLdD-UYoSzGyKmzIBI76vsVv5xbkhKwnLBnmX2ssRHMfOgIuyEpG16SwNiyKuBOZdhC39dapEWwSn2bzWqSi4Y-LvIdsANlHfgdwzVzkJNfNAO-2oOMQC4h-QfBlUVoSEQPYLPmGDOUpcawnHXc60Lyg9rCdxooG9YVzXUeqoi4SIc8feHH4My4s_Eb9mprP6sewezTIb4ldPCVwAlh2xl5BrWYDLLNbhgVMmUVaNZjXSS40egT4xxIWiNPw4axCAKZbgsk78lgHo51t0hz8j6qIfn9G_ZNzMagKQRupx4guuMQXiXg30WjSE09HBv6QjDLQRz9A89eRAKCiGVddKGAvXy_cZrAi2OZ_gtsX993wR-kt6AtNZ7s2U5IZPribvLbiNBMtwh1kRfz_t_bUFLCJs7J332odSDkxL38LqR7oRNStZv6EqAXmelWYqBsUvnwZWI3DYqjysYfjb4JALSTwOa4zfDHDkzlaKOiIZwZkI0GroSed_fmL6cfkpmN63CRY3qNQfwG7cXT0mOuOTJSzRBw1QigfCVnM_M2881eBaBdpdwXw3zF7FlxJL1Y0uMSQ0RZ2l3WC81xH7KqUUlUPw\",\r\n \"type\": \"blogs\",\r\n \"filters\": \"active:true\"\r\n }\r\n },\r\n \"document\" : {\r\n \"type\" : \"content\"\r\n },\r\n \"mapping\": {},\r\n \"languages\":{}\r\n}]" \
-H "Content-Type: application/json" \
-H "mode: F" \
-H "type: content" |
In the sample above, the following BODY is used:
| Expand | |||||
|---|---|---|---|---|---|
| |||||
|
LANGUAGES
This must be declared in order to map the exported language (ex: “de”) with your connector export value (ex:”en-de”).
| Code Block |
|---|
"languages": {
"de": "en-de",
"fr": "fr-ch"
} |
AVAILABLE SERVICES
In order to allow our integrators to validate that the existing data available in the 3rd party systems is properly exported, a few helper services are available:
TEST REQUEST
Use a simple TEST request in order to validate that the connection to your configured endpoint (connector property) is valid.
| Code Block | |
|---|---|
curl https://boxalino-di-transformer-krceabfwya-ew.a.run.app/test \
-X POST \
-d "[{\"connector\":{\"type\":\"prismic\",\"options\":{\"url\":\"https:\/\/rtux-integration.cdn.prismic.io\/api\/v2\/\",\"access_token\":\"MC5ZSkU4SnhBQUFDSUFXSXZR.77-9QO-_vWR577-977-9HO-_ve-_ve-_vXPvv73vv71LeO-_vUNi77-9Ii3vv73vv73vv71sC2Xvv71A77-9IA\",\"query\":[\"[at(document.type, \\\"category\\\")]\"]}},\"document\":{},\"mapping\":{},\"languages\":{
|
SAMPLE REQUEST
You can also use the SAMPLE trigger in order to access one element of the given types.
The JSON response will be the JSONL structure as it is exported to Boxalino GCS.
| Tip |
|---|
Use this service to validate & check that all your data is exported as desired. |
| Code Block |
|---|
curl https://boxalino-di-transformer-krceabfwya-ew.a.run.app/sample \ -X POST \ -d "[{\"connector\":{\"type\":\"prismic\",\"options\":{\"url\":\"https:\/\/rtux-integration.cdn.prismic.io\/api\/v2\/\",\"access_token\":\"MC5ZSkU4SnhBQUFDSUFXSXZR.77-9QO-_vWR577-977-9HO-_ve-_ve-_vXPvv73vv71LeO-_vUNi77-9Ii3vv73vv73vv71sC2Xvv71A77-9IA\",\"query\":[\"[at(document.type, \\\"category\\\")]\"]}},\"document\":{\"type\":\"content\"},\"mapping\":{\"id\":\"id\",\"type\":\"type\",\"creation\":\"first_publication_date\",\"last_update\":\"last_publication_date\",\"persona_type\":\"\",\"persona_id\":\"\",\"title\":\"data.name\",\"short_description\":\"\",\"description\":\"data.description\",\"images\":\"data.header_image.url\",\"link\":\"uid\",\"tags\":{\"default\":\"tags\"},\"parent_content_ids\":\"data.parent_category.id\",\"contents\":[],\"products\":[],\"customers\":[],\"stores\":\"\",\"status\":\"data.status\",\"string_attributes\":{\"default_tags\":\"tags\",\"version\":\"version\"},\"localized_string_attributes\":{\"category_title\":\"data.category_title\",\"slugs\":\"slugs\",\"linked_language_id\":\"alternate_languages[*].id\"},\"numeric_attributes\":{\"position\":\"data.position\",\"show_in_navigation\":\"data.show_in_navigation\"},\"localized_numeric_attributes\":{},\"datetime_attributes\":{},\"localized_datetime_attributes\":{}},\"languages\":{\"de\":\"en-de\",\"fr\":\"fr-ch\"}},{\"connector\":{\"type\":\"prismic\",\"options\":{\"url\":\"https:\/\/rtux-integration.cdn.prismic.io\/api\/v2\/\",\"access_token\":\"MC5ZSkU4SnhBQUFDSUFXSXZR.77-9QO-_vWR577-977-9HO-_ve-_ve-_vXPvv73vv71LeO-_vUNi77-9Ii3vv73vv73vv71sC2Xvv71A77-9IA\",\"query\":[\"[at(document.type, \\\"blog\\\")]\"]}},\"document\":{\"type\":\"content\"},\"mapping\":{\"id\":\"id\",\"type\":\"type\",\"creation\":\"first_publication_date\",\"last_update\":\"last_publication_date\",\"persona_type\":\"\",\"persona_id\":\"\",\"title\":\"data.title\",\"short_description\":\"\",\"description\":\"data.content\",\"images\":\"data.header_image.url\",\"link\":\"uid\",\"tags\":{\"default\":\"tags\",\"category\":\"data.category.tags\"},\"parent_content_ids\":\"data.category.id\",\"contents\":[],\"products\":[],\"customers\":[],\"stores\":\"\",\"status\":\"data.status\",\"string_attributes\":{\"tags\":\"tags\",\"category_uid\":\"data.category.uid\"},\"localized_string_attributes\":{\"slugs\":\"slugs\",\"alternate_languages\":\"alternate_languages[*].id\",\"meta_title\":\"data.meta_title\",\"content\":\"data.content\"},\"numeric_attributes\":{\"position\":\"data.position\"},\"localized_numeric_attributes\":{\"product_ids\":\"data.product_ids[*].id\"},\"datetime_attributes\":{},\"localized_datetime_attributes\":{}},\"languages\":{\"de\":\"en-de\",\"fr\":\"fr-ch\"}},{\"connector\":{\"type\":\"prismicgraphql\",\"options\":{\"urlendpoint\":\"https:\/\/rtux-integration.cdn.prismic.io\/api\/v2\/api-eu-central-1.graphcms.com\/v2\/ckll4a83ni7og01yzfr3k9yc4\/master\",\"access_token\":\"MC5ZSkU4SnhBQUFDSUFXSXZR.77-9QO-_vWR577-977-9HO-_ve-_ve-_vXPvv73vv71LeO-_vUNi77-9Ii3vv73vv73vv71sC2Xvv71A77-9IAeyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImdjbXMtbWFpbi1wcm9kdWN0aW9uIn0.eyJ2ZXJzaW9uIjozLCJpYXQiOjE2MjI1NjIzMzMsImF1ZCI6WyJodHRwczovL2FwaS1ldS1jZW50cmFsLTEuZ3JhcGhjbXMuY29tL3YyL2NrbGw0YTgzbmk3b2cwMXl6ZnIzazl5YzQvbWFzdGVyIiwiaHR0cHM6Ly9tYW5hZ2VtZW50LW5leHQuZ3JhcGhjbXMuY29tIl0sImlzcyI6Imh0dHBzOi8vbWFuYWdlbWVudC5ncmFwaGNtcy5jb20vIiwic3ViIjoiZjZlMTcyNGYtOTI2NS00OTFjLWEwMzktYzFkNGI2ZDExZDA5IiwianRpIjoiY2twZTdweDVoZGR2bzAxejU1NjNwZjc1cCJ9.MjYP8I7OvwyOkiHiB22LPwOfRzEt_ilvp6jHTVufkQEs6UTxJeuOEDvcojbMAgiEa3lStbc3mOVDezOQhMoLdD-UYoSzGyKmzIBI76vsVv5xbkhKwnLBnmX2ssRHMfOgIuyEpG16SwNiyKuBOZdhC39dapEWwSn2bzWqSi4Y-LvIdsANlHfgdwzVzkJNfNAO-2oOMQC4h-QfBlUVoSEQPYLPmGDOUpcawnHXc60Lyg9rCdxooG9YVzXUeqoi4SIc8feHH4My4s_Eb9mprP6sewezTIb4ldPCVwAlh2xl5BrWYDLLNbhgVMmUVaNZjXSS40egT4xxIWiNPw4axCAKZbgsk78lgHo51t0hz8j6qIfn9G_ZNzMagKQRupx4guuMQXiXg30WjSE09HBv6QjDLQRz9A89eRAKCiGVddKGAvXy_cZrAi2OZ_gtsX993wR-kt6AtNZ7s2U5IZPribvLbiNBMtwh1kRfz_t_bUFLCJs7J332odSDkxL38LqR7oRNStZv6EqAXmelWYqBsUvnwZWI3DYqjysYfjb4JALSTwOa4zfDHDkzlaKOiIZwZkI0GroSed_fmL6cfkpmN63CRY3qNQfwG7cXT0mOuOTJSzRBw1QigfCVnM_M2881eBaBdpdwXw3zF7FlxJL1Y0uMSQ0RZ2l3WC81xH7KqUUlUPw\",\"type\":\"blogs\",\"filters\":\"active:true\",\"queryfields\":[\"[at(document.type, \\\"blog\\\")]\"{ title __typename locale createdAt active id metaDescription metaTitle publishedAt seoLink updatedAt content { html text } headerImage { url id } stage background { css hex } brands { id name } createdBy { id name } history { createdAt } publishedBy { id name } updatedBy { id name } }\",\"locales\":[\"de_CH\",\"fr_CH\"]}},\"document\":{},\"mappingtype\":{\"content\"},\"languagesmapping\":{}}]\" id\ -H "Content-Type: application/json" \ -H "mode: F" \ -H "type: content" |
In the sample above, the following BODY is used:
...
| title | JSON body content for TEST request |
|---|
| Code Block | ||
|---|---|---|
| ||
[
{
"connector": {
"type": "prismic",
"options": {
"url": "https://rtux-integration.cdn.prismic.io/api/v2/",
"access_token": "MC5ZSkU4SnhBQUFDSUFXSXZR.77-9QO-_vWR577-977-9HO-_ve-_ve-_vXPvv73vv71LeO-_vUNi77-9Ii3vv73vv73vv71sC2Xvv71A77-9IA",
"query": [
"[at(document.type, \"category\")]"
]
}
},
"document": {},
"mapping": {},
"languages": {}
},
{
"connector": {
"type": "prismic",
"options": {
"url": "https://rtux-integration.cdn.prismic.io/api/v2/",
"access_token": "MC5ZSkU4SnhBQUFDSUFXSXZR.77-9QO-_vWR577-977-9HO-_ve-_ve-_vXPvv73vv71LeO-_vUNi77-9Ii3vv73vv73vv71sC2Xvv71A77-9IA",
"query": [
"[at(document.type, \"blog\")]"
]
}
},
"document": {},
"mapping": {},
"languages": {}
}
] |
SAMPLE REQUEST
You can also use the SAMPLE trigger in order to access one element of the given types.
The JSON response will be the JSONL structure as it is exported to Boxalino GCS.
| Tip |
|---|
Use this service to validate & check that all your data is exported as desired. |
| Code Block |
|---|
curl https://boxalino-di-transformer-krceabfwya-ew.a.run.app/sample \
-X POST \
-d "[{\"connector\":{\"type\":\"prismic\",\"options\":{\"url\":\"https:\/\/rtux-integration.cdn.prismic.io\/api\/v2\/\",\"access_token\":\"MC5ZSkU4SnhBQUFDSUFXSXZR.77-9QO-_vWR577-977-9HO-_ve-_ve-_vXPvv73vv71LeO-_vUNi77-9Ii3vv73vv73vv71sC2Xvv71A77-9IA\",\"query\":[\"[at(document.type, \\\"category\\\")]\"]}},\"document\":{\"type\":\"content\"},\"mapping\":{\"id\":\"id\",\"type\":\"type\",\"creation\":\"first_publication_date\",\"last_update\":\"last_publication_date\",\"persona_type\":\"\",\"persona_id\":\"\",\"title\":\"data.name\",\"short_description\":\"\",\"description\":\"data.description\",\"images\":\"data.header_image.url\",\"link\":\"uid\",\"tags\":{\"default\":\"tags\"},\"parent_content_ids\":\"data.parent_category.id\",\"contents\":[],\"products\":[],\"customers\":[],\"stores\":\"\",\"status\":\"data.status\",\"string_attributes\":{\"default_tags\":\"tags\",\"version\":\"version\"},\"localized_string_attributes\":{\"category_title\":\"data.category_title\",\"slugs\":\"slugs\",\"linked_language_id\":\"alternate_languages[*].id\"},\"numeric_attributes\":{\"position\":\"data.position\",\"show_in_navigation\":\"data.show_in_navigation\"},\"localized_numeric_attributes\":{},\"datetime_attributes\":{},\"localized_datetime_attributes\":{}},\"languages\":{\"de\":\"en-de\",\"fr\":\"fr-ch\"}},{\"connector\":{\"type\":\"prismic\",\"options\":{\"url\":\"https:\/\/rtux-integration.cdn.prismic.io\/api\/v2\/\",\"access_token\":\"MC5ZSkU4SnhBQUFDSUFXSXZR.77-9QO-_vWR577-977-9HO-_ve-_ve-_vXPvv73vv71LeO-_vUNi77-9Ii3vv73vv73vv71sC2Xvv71A77-9IA\",\"query\":[\"[at(document.type, \\\"blog\\\")]\"]}},\"document\":{\"type\":\"content\"},\"mapping\":{\"id\":\"id\",\"type\":\"type\",\"creation\":\"first_publication_date\",\"last_update\":\"last_publication_date\",\"persona_type\":\"\",\"persona_id\":\"\",\"title\":\"data.title\",\"short_description\":\"\",\"description\":\"data.content\",\"images\":\"data.header_image.url\",\"link\":\"uid\",\"tags\":{\"default\":\"tags\",\"category\":\"data.category.tags\"},\"parent_content_ids\":\"data.category.id\",\"contents\":[],\"products\":[],\"customers\":[],\"stores\":\"\",\"status\":\"data.status\",\"string_attributes\":{\"tags\":\"tags\",\"category_uid\":\"data.category.uid\"},\"localized_string_attributes\":{\"slugs\":\"slugs\",\"alternate_languages\":\"alternate_languages[*].id\",\"meta_title\":\"data.meta_title\",\"content\":\"data.content\"},\"numeric_attributes\":{\"position\":\"data.position\"},\"localized_numeric_attributes\":{\"product_ids\":\"data.product_ids[*].id\"},\"datetime_attributes\":{},\"localized_datetime_attributes\":{}},\"languages\":{\"de\":\"en-de\",\"fr\":\"fr-ch\"}}]" \
-H "Content-Type: application/json" \
-H "mode: F" \
-H "type: content" |
In the sample above, the following BODY is used:
| Expand | ||
|---|---|---|
| ||
| Code Block | | |
|
In the sample above, the following BODY is used:
| Expand | |||||
|---|---|---|---|---|---|
| |||||
|