diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a7b5e9b64..bdf987edc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -15,7 +15,7 @@ jobs: - name: Setup Ruby uses: ruby/setup-ruby@v1 with: - ruby-version: '3.1' # Not needed with a .ruby-version file + ruby-version: '3.2' # Not needed with a .ruby-version file bundler-cache: true # runs 'bundle install' and caches installed gems automatically cache-version: 0 # Increment this number if you need to re-download cached gems - name: Build with Jekyll diff --git a/Gemfile.lock b/Gemfile.lock index 2b5f3c5f4..6b14d89c7 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,21 +1,58 @@ GEM remote: https://rubygems.org/ specs: - addressable (2.8.6) - public_suffix (>= 2.0.2, < 6.0) + addressable (2.8.7) + public_suffix (>= 2.0.2, < 7.0) + bigdecimal (3.2.2) colorator (1.1.0) - concurrent-ruby (1.2.3) + concurrent-ruby (1.3.5) em-websocket (0.5.3) eventmachine (>= 0.12.9) http_parser.rb (~> 0) eventmachine (1.2.7) - ffi (1.16.3) + ffi (1.17.2) + ffi (1.17.2-aarch64-linux-gnu) + ffi (1.17.2-aarch64-linux-musl) + ffi (1.17.2-arm-linux-gnu) + ffi (1.17.2-arm-linux-musl) + ffi (1.17.2-arm64-darwin) + ffi (1.17.2-x86-linux-gnu) + ffi (1.17.2-x86-linux-musl) + ffi (1.17.2-x86_64-darwin) + ffi (1.17.2-x86_64-linux-gnu) + ffi (1.17.2-x86_64-linux-musl) forwardable-extended (2.6.0) - google-protobuf (3.25.3-x86_64-linux) + google-protobuf (4.31.1) + bigdecimal + rake (>= 13) + google-protobuf (4.31.1-aarch64-linux-gnu) + bigdecimal + rake (>= 13) + google-protobuf (4.31.1-aarch64-linux-musl) + bigdecimal + rake (>= 13) + google-protobuf (4.31.1-arm64-darwin) + bigdecimal + rake (>= 13) + google-protobuf (4.31.1-x86-linux-gnu) + bigdecimal + rake (>= 13) + google-protobuf (4.31.1-x86-linux-musl) + bigdecimal + rake (>= 13) + google-protobuf (4.31.1-x86_64-darwin) + bigdecimal + rake (>= 13) + google-protobuf (4.31.1-x86_64-linux-gnu) + bigdecimal + rake (>= 13) + google-protobuf (4.31.1-x86_64-linux-musl) + bigdecimal + rake (>= 13) http_parser.rb (0.8.0) - i18n (1.14.4) + i18n (1.14.7) concurrent-ruby (~> 1.0) - jekyll (4.3.3) + jekyll (4.3.4) addressable (~> 2.4) colorator (~> 1.0) em-websocket (~> 0.5) @@ -33,8 +70,8 @@ GEM webrick (~> 1.7) jekyll-include-cache (0.2.1) jekyll (>= 3.7, < 5.0) - jekyll-sass-converter (3.0.0) - sass-embedded (~> 1.54) + jekyll-sass-converter (3.1.0) + sass-embedded (~> 1.75) jekyll-seo-tag (2.8.0) jekyll (>= 3.8, < 5.0) jekyll-watch (2.2.1) @@ -44,8 +81,8 @@ GEM jekyll-include-cache jekyll-seo-tag (>= 2.0) rake (>= 12.3.1) - kramdown (2.4.0) - rexml + kramdown (2.5.1) + rexml (>= 3.3.9) kramdown-parser-gfm (1.1.0) kramdown (~> 2.0) liquid (4.0.4) @@ -55,27 +92,74 @@ GEM mercenary (0.4.0) pathutil (0.16.2) forwardable-extended (~> 2.6) - public_suffix (5.0.5) - rake (13.2.1) + public_suffix (6.0.2) + rake (13.3.0) rb-fsevent (0.11.2) - rb-inotify (0.10.1) + rb-inotify (0.11.1) ffi (~> 1.0) - rexml (3.2.6) - rouge (4.2.1) + rexml (3.4.1) + rouge (4.5.2) safe_yaml (1.0.5) - sass-embedded (1.63.6-x86_64-linux-gnu) - google-protobuf (~> 3.23) + sass-embedded (1.89.2) + google-protobuf (~> 4.31) + rake (>= 13) + sass-embedded (1.89.2-aarch64-linux-android) + google-protobuf (~> 4.31) + sass-embedded (1.89.2-aarch64-linux-gnu) + google-protobuf (~> 4.31) + sass-embedded (1.89.2-aarch64-linux-musl) + google-protobuf (~> 4.31) + sass-embedded (1.89.2-arm-linux-androideabi) + google-protobuf (~> 4.31) + sass-embedded (1.89.2-arm-linux-gnueabihf) + google-protobuf (~> 4.31) + sass-embedded (1.89.2-arm-linux-musleabihf) + google-protobuf (~> 4.31) + sass-embedded (1.89.2-arm64-darwin) + google-protobuf (~> 4.31) + sass-embedded (1.89.2-riscv64-linux-android) + google-protobuf (~> 4.31) + sass-embedded (1.89.2-riscv64-linux-gnu) + google-protobuf (~> 4.31) + sass-embedded (1.89.2-riscv64-linux-musl) + google-protobuf (~> 4.31) + sass-embedded (1.89.2-x86_64-darwin) + google-protobuf (~> 4.31) + sass-embedded (1.89.2-x86_64-linux-android) + google-protobuf (~> 4.31) + sass-embedded (1.89.2-x86_64-linux-gnu) + google-protobuf (~> 4.31) + sass-embedded (1.89.2-x86_64-linux-musl) + google-protobuf (~> 4.31) terminal-table (3.0.2) unicode-display_width (>= 1.1.1, < 3) - unicode-display_width (2.5.0) - webrick (1.8.1) + unicode-display_width (2.6.0) + webrick (1.9.1) PLATFORMS - x86_64-linux + aarch64-linux-android + aarch64-linux-gnu + aarch64-linux-musl + arm-linux-androideabi + arm-linux-gnu + arm-linux-gnueabihf + arm-linux-musl + arm-linux-musleabihf + arm64-darwin + riscv64-linux-android + riscv64-linux-gnu + riscv64-linux-musl + ruby + x86-linux-gnu + x86-linux-musl + x86_64-darwin + x86_64-linux-android + x86_64-linux-gnu + x86_64-linux-musl DEPENDENCIES jekyll (~> 4.3.3) just-the-docs (= 0.8.2) BUNDLED WITH - 2.4.20 + 2.6.9 diff --git a/_data/components/common/attributes.yml b/_data/components/common/attributes.yml index 8fc45faad..68c15e189 100644 --- a/_data/components/common/attributes.yml +++ b/_data/components/common/attributes.yml @@ -465,5 +465,14 @@ default: "[10, 25, 50, 100]", required: "", description: "Page size options separated by ';'." - } + }, + "configure-service-args": { + name: "configure-service-args", + type: "OConfigureServiceArgs", + since: "15.6.0", + default: "no", + required: "", + description: "Allows configure service" + } + } diff --git a/_data/components/form.yml b/_data/components/form.yml index c386946e5..f40a197b1 100644 --- a/_data/components/form.yml +++ b/_data/components/form.yml @@ -185,7 +185,8 @@ attributes: [ type: "(data: any) => OFormValidation", since: "15.4.2", description: "Executes the before-save validation callback for insert and update operations." - +},{ + name: "configure-service-args" }] outputs: [{ diff --git a/_data/components/grid.yml b/_data/components/grid.yml index 758410447..faa0eb343 100644 --- a/_data/components/grid.yml +++ b/_data/components/grid.yml @@ -6,7 +6,7 @@ apiTitle: "OGridComponent" inheritedAttributes: [{ component: "OServiceBaseComponent", path: "components/service/service-base/api", - attributes: ["attr", "service", "service-type", "entity", "query-on-init", "query-fallback-function", "query-on-bind", "pageable", "columns", "keys", "parent-keys", "static-data", "query-method", "paginated-query-method", "query-rows", "store-state", "query-with-null-parent-keys"] + attributes: ["attr", "service", "service-type", "entity", "query-on-init", "query-fallback-function", "query-on-bind", "pageable", "columns", "keys", "parent-keys", "static-data", "query-method", "paginated-query-method", "query-rows", "store-state", "query-with-null-parent-keys", "configure-service-args"] },{ component: "OServiceComponent", path: "components/service/service/api", diff --git a/_data/components/list.yml b/_data/components/list.yml index ceafb6b86..768826842 100644 --- a/_data/components/list.yml +++ b/_data/components/list.yml @@ -5,7 +5,7 @@ apiTitle: "OListComponent" inheritedAttributes: [{ component: "OServiceBaseComponent", path: "components/service/service-base/api", - attributes: ["attr", "service", "service-type", "entity","query-fallback-function", "query-on-init", "query-on-bind", "pageable", "columns", "keys", "parent-keys", "static-data", "query-method", "paginated-query-method", "query-rows", "insert-method", "update-method", "delete-method", "store-state", "query-with-null-parent-keys"] + attributes: ["attr", "service", "service-type", "entity","query-fallback-function", "query-on-init", "query-on-bind", "pageable", "columns", "keys", "parent-keys", "static-data", "query-method", "paginated-query-method", "query-rows", "insert-method", "update-method", "delete-method", "store-state", "query-with-null-parent-keys", "configure-service-args"] },{ component: "OServiceComponent", path: "components/service/service/api", diff --git a/_data/components/ocomboData/00combo.yml b/_data/components/ocomboData/00combo.yml index e59e09853..3bb86ab7b 100644 --- a/_data/components/ocomboData/00combo.yml +++ b/_data/components/ocomboData/00combo.yml @@ -7,7 +7,7 @@ inheritedAttributes: [{ },{ component: "OFormServiceComponent", path: "components/input/overviewservice/api", - attributes: ["static-data", "entity", "service", "columns", "value-column", "value-column-type", "parent-keys", "description-columns", "separator", "query-on-init", "query-on-bind", "query-on-event", "query-method", "service-type", "query-with-null-parent-keys", "set-value-on-value-change", "translate", "sort"] + attributes: ["static-data", "entity", "service", "columns", "value-column", "value-column-type", "parent-keys", "description-columns", "separator", "query-on-init", "query-on-bind", "query-on-event", "query-method", "service-type", "query-with-null-parent-keys", "set-value-on-value-change", "translate", "sort", "configure-service-args"] }] inheritedOutputs: [{ diff --git a/_data/components/olistpickerData/00listPicker.yml b/_data/components/olistpickerData/00listPicker.yml index 82ce273cd..9cd1e8a93 100644 --- a/_data/components/olistpickerData/00listPicker.yml +++ b/_data/components/olistpickerData/00listPicker.yml @@ -7,7 +7,7 @@ inheritedAttributes: [{ },{ component: "OFormServiceComponent", path: "components/input/overviewservice/api", - attributes: ["static-data", "entity", "service", "columns", "value-column", "value-column-type", "parent-keys", "description-columns", "separator", "query-on-init", "query-on-bind", "query-on-event", "query-method", "service-type", "query-with-null-parent-keys", "set-value-on-value-change", "translate", "sort"] + attributes: ["static-data", "entity", "service", "columns", "value-column", "value-column-type", "parent-keys", "description-columns", "separator", "query-on-init", "query-on-bind", "query-on-event", "query-method", "service-type", "query-with-null-parent-keys", "set-value-on-value-change", "translate", "sort", "configure-service-args"] }] attributes: [{ diff --git a/_data/components/otableData/00table.yml b/_data/components/otableData/00table.yml index 6a12ac583..bd7fa1c0f 100644 --- a/_data/components/otableData/00table.yml +++ b/_data/components/otableData/00table.yml @@ -5,7 +5,7 @@ directive: "o-table" inheritedAttributes: [{ component: "OServiceBaseComponent", path: "components/service/service-base/api", - attributes: ["attr", "service", "service-type", "entity", "query-fallback-function", "query-on-init", "query-on-bind", "pageable", "columns", "keys *", "parent-keys", "static-data", "query-method", "paginated-query-method", "query-rows", "insert-method", "update-method", "delete-method", "store-state", "query-with-null-parent-keys"] + attributes: ["attr", "service", "service-type", "entity", "query-fallback-function", "query-on-init", "query-on-bind", "pageable", "columns", "keys *", "parent-keys", "static-data", "query-method", "paginated-query-method", "query-rows", "insert-method", "update-method", "delete-method", "store-state", "query-with-null-parent-keys", "configure-service-args"] },{ component: "OServiceComponent", path: "components/service/service/api", diff --git a/_data/components/otableData/renderers/09tableColumnRendererService.yml b/_data/components/otableData/renderers/09tableColumnRendererService.yml index 08f2a0bdc..0769fa160 100644 --- a/_data/components/otableData/renderers/09tableColumnRendererService.yml +++ b/_data/components/otableData/renderers/09tableColumnRendererService.yml @@ -22,6 +22,8 @@ attributes: [{ name: "query-method" },{ name: "service-type" +},{ + name: "configure-service-args" }] inherit_properties: [{ diff --git a/_data/components/overviewService.yml b/_data/components/overviewService.yml index 1ba0bd127..75159bfef 100644 --- a/_data/components/overviewService.yml +++ b/_data/components/overviewService.yml @@ -79,6 +79,8 @@ attributes: [{ default: "", required: "", description: "Indicates the order ascending or descending of the option values" +},{ + name: "configure-service-args" }] outputs: [{ diff --git a/_data/components/overviewchart.yml b/_data/components/overviewchart.yml index 07e257e0e..5cf40ef63 100644 --- a/_data/components/overviewchart.yml +++ b/_data/components/overviewchart.yml @@ -5,7 +5,7 @@ apiTitle: "OChartComponent" inheritedAttributes: [{ component: "OServiceBaseComponent", path: "components/service/service-base/api", - attributes: ["attr", "service", "service-type", "entity", "query-fallback-function", "query-on-init", "query-on-bind", "pageable", "columns", "keys", "parent-keys", "static-data", "query-method", "query-rows", "store-state", "query-with-null-parent-keys"] + attributes: ["attr", "service", "service-type", "entity", "query-fallback-function", "query-on-init", "query-on-bind", "pageable", "columns", "keys", "parent-keys", "static-data", "query-method", "query-rows", "store-state", "query-with-null-parent-keys", "configure-service-args"] }] attributes: [{ diff --git a/_data/components/radio.yml b/_data/components/radio.yml index afe9f8c95..2dcad1e32 100644 --- a/_data/components/radio.yml +++ b/_data/components/radio.yml @@ -9,7 +9,7 @@ inheritedAttributes: [{ },{ component: "OFormServiceComponent", path: "components/input/overviewservice/api", - attributes: ["static-data", "entity", "service", "columns", "value-column", "value-column-type", "parent-keys", "visible-columns", "separator", "query-on-init", "query-on-bind", "query-on-event", "query-method", "service-type", "query-with-null-parent-keys", "set-value-on-value-change", "translate", "sort"] + attributes: ["static-data", "entity", "service", "columns", "value-column", "value-column-type", "parent-keys", "visible-columns", "separator", "query-on-init", "query-on-bind", "query-on-event", "query-method", "service-type", "query-with-null-parent-keys", "set-value-on-value-change", "translate", "sort", "configure-service-args"] }] inheritedOutputs: [{ diff --git a/_data/components/service.yml b/_data/components/service.yml index 1afa5b450..42021a388 100644 --- a/_data/components/service.yml +++ b/_data/components/service.yml @@ -5,7 +5,7 @@ propertiesColumns: ["Name", "Type", "Required", "Description"] inheritedAttributes: [{ component: "OServiceBaseComponent", path: "components/service/service-base/api", - attributes: ["attr", "static-data", "service", "service-type","query-fallback-function", "query-method", "entity", "keys", "parent-keys", "columns", "query-on-init", "query-on-bind", "query-rows", "insert-method", "update-method", "paginated-query-method", "delete-method", "pageable", "store-state", "query-with-null-parent-keys"] + attributes: ["attr", "static-data", "service", "service-type","query-fallback-function", "query-method", "entity", "keys", "parent-keys", "columns", "query-on-init", "query-on-bind", "query-rows", "insert-method", "update-method", "paginated-query-method", "delete-method", "pageable", "store-state", "query-with-null-parent-keys", "configure-service-args"] }] attributes: [{ diff --git a/_data/components/serviceBase.yml b/_data/components/serviceBase.yml index 990701f8b..4583fc1c1 100644 --- a/_data/components/serviceBase.yml +++ b/_data/components/serviceBase.yml @@ -55,6 +55,8 @@ attributes: [{ description: "Function to execute on query error", type: "Function", default: "No value" +},{ + name: "configure-service-args" } ] diff --git a/_data/menu_descriptions.yml b/_data/menu_descriptions.yml index 6dc272541..5490bf5ad 100644 --- a/_data/menu_descriptions.yml +++ b/_data/menu_descriptions.yml @@ -418,3 +418,11 @@ sections: - url: "/addons/report/" title: "Report" imagepath: "/assets/images/menus/addons/report" + "services": + - url: "/guide/service/jsonapi" + title: "JSON:API " + imagepath: "/assets/images/menus/services/jsonapi" + - url: "/guide/service/ontimize" + title: "Ontimize" + imagepath: "/assets/images/menus/services/ontimize" + diff --git a/_includes/nav_cards.html b/_includes/nav_cards.html index fbbef5fa4..696626b64 100644 --- a/_includes/nav_cards.html +++ b/_includes/nav_cards.html @@ -20,8 +20,6 @@ - -
diff --git a/assets/examples/jsonapi_service_request_example_response.json b/assets/examples/jsonapi_service_request_example_response.json new file mode 100644 index 000000000..d45ff3680 --- /dev/null +++ b/assets/examples/jsonapi_service_request_example_response.json @@ -0,0 +1,128 @@ +{ + "data": [ + { + "attributes": { + "CategoryName": "Beverages", + "Client_id": 1, + "Description": "Soft drinks, coffees, teas, beers, and ales", + "Id": 1 + }, + "id": "1", + "links": { + "self": "/api/Category/1/" + }, + "relationships": {}, + "type": "Category" + }, + { + "attributes": { + "CategoryName": "Condiments", + "Client_id": 2, + "Description": "Sweet and savory sauces, relishes, spreads, and seasonings", + "Id": 2 + }, + "id": "2", + "links": { + "self": "/api/Category/2/" + }, + "relationships": {}, + "type": "Category" + }, + { + "attributes": { + "CategoryName": "Confections", + "Client_id": 2, + "Description": "Desserts, candies, and sweet breads", + "Id": 3 + }, + "id": "3", + "links": { + "self": "/api/Category/3/" + }, + "relationships": {}, + "type": "Category" + }, + { + "attributes": { + "CategoryName": "Dairy Products", + "Client_id": 2, + "Description": "Cheeses", + "Id": 4 + }, + "id": "4", + "links": { + "self": "/api/Category/4/" + }, + "relationships": {}, + "type": "Category" + }, + { + "attributes": { + "CategoryName": "Grains/Cereals", + "Client_id": 3, + "Description": "Breads, crackers, pasta, and cereal", + "Id": 5 + }, + "id": "5", + "links": { + "self": "/api/Category/5/" + }, + "relationships": {}, + "type": "Category" + }, + { + "attributes": { + "CategoryName": "Meat/Poultry", + "Client_id": 3, + "Description": "Prepared meats", + "Id": 6 + }, + "id": "6", + "links": { + "self": "/api/Category/6/" + }, + "relationships": {}, + "type": "Category" + }, + { + "attributes": { + "CategoryName": "Produce", + "Client_id": 3, + "Description": "Dried fruit and bean curd", + "Id": 7 + }, + "id": "7", + "links": { + "self": "/api/Category/7/" + }, + "relationships": {}, + "type": "Category" + }, + { + "attributes": { + "CategoryName": "Seafood", + "Client_id": 3, + "Description": "Seaweed and fish", + "Id": 8 + }, + "id": "8", + "links": { + "self": "/api/Category/8/" + }, + "relationships": {}, + "type": "Category" + } + ], + "included": [], + "jsonapi": { + "version": "1.0" + }, + "links": { + "self": "/api/Category/?fields[Category]=CategoryName,Description,Client_id,Id&sort=CategoryName&page[offset]=0&page[limit]=20" + }, + "meta": { + "count": 8, + "limit": 20, + "total": 8 + } +} \ No newline at end of file diff --git a/assets/images/jsonapi-request.png b/assets/images/jsonapi-request.png new file mode 100644 index 000000000..bb0f9a6e5 Binary files /dev/null and b/assets/images/jsonapi-request.png differ diff --git a/assets/images/jsonapi-response.png b/assets/images/jsonapi-response.png new file mode 100644 index 000000000..e84620f1f Binary files /dev/null and b/assets/images/jsonapi-response.png differ diff --git a/assets/images/menus/services/jsonapi.svg b/assets/images/menus/services/jsonapi.svg new file mode 100644 index 000000000..86010d9db --- /dev/null +++ b/assets/images/menus/services/jsonapi.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/assets/images/menus/services/jsonapi_dark.svg b/assets/images/menus/services/jsonapi_dark.svg new file mode 100644 index 000000000..abc168223 --- /dev/null +++ b/assets/images/menus/services/jsonapi_dark.svg @@ -0,0 +1,9 @@ + + + \ No newline at end of file diff --git a/assets/images/menus/services/ontimize.svg b/assets/images/menus/services/ontimize.svg new file mode 100644 index 000000000..42be207c5 --- /dev/null +++ b/assets/images/menus/services/ontimize.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/assets/images/menus/services/ontimize_dark.svg b/assets/images/menus/services/ontimize_dark.svg new file mode 100644 index 000000000..f50b024e3 --- /dev/null +++ b/assets/images/menus/services/ontimize_dark.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/docs/addons/ontimize_web_ngx_report/components/jsonapi.md b/docs/addons/ontimize_web_ngx_report/components/jsonapi.md new file mode 100644 index 000000000..729a1f2f6 --- /dev/null +++ b/docs/addons/ontimize_web_ngx_report/components/jsonapi.md @@ -0,0 +1,37 @@ +--- +title: "Report store" +permalink: /addons/report/components/report-store/jsonapi +layout: default +parent: Report store +grand_parent: Report +nav_order: 4 +--- +# Introduction +The *Report Store** system will allow you to store, manage and export all kinds of reports designed and implemented via the JasperReports API. This module will let you use your Ontimize application data as data sources for your reports, allowing you to fully customize its layout with tables, charts, graphs… and also visualize, export, print and download your reports. + + +# Previous concepts +* Report: It is the generic representation of a report. One report can have one or multiple custom report parameters, or have none. +* Main report file: The file containing all the information regarding the report layout, along with the data sources, connections and other configuration directives. Written in .jrxml format. +* Report parameter: It is the generic representation of a custom report parameter. They are used for defining filters, implementing pagination, or even specifying the report data source. + +# Steps +```ts + { + "REPORTUUID": string + "REPORTNAME": string + "REPORTTYPE": string + "REPORTDESCRIPTION": string + "REPORTFILENAME":string + + }; + { + REPORTPARAMETERID:number, INTEGER PRIMARY KEY AUTOINCREMENT, + REPORTPARAMETERNAME:string, + REPORTPARAMETERDESCRIPTION: string, + REPORTPARAMETERNESTEDTYPE: string, + REPORTPARAMETERVALUECLASS: string, + REPORTUUID:string + } + + diff --git a/docs/addons/ontimize_web_ngx_report/components/report-store.md b/docs/addons/ontimize_web_ngx_report/components/report-store.md index 6f3fe05a2..d3e0ec648 100644 --- a/docs/addons/ontimize_web_ngx_report/components/report-store.md +++ b/docs/addons/ontimize_web_ngx_report/components/report-store.md @@ -7,13 +7,35 @@ grand_parent: Addons nav_order: 3 --- +Report store supports **OntimizeEE** and **JSON:API** standards. + +{: .note} +>Remember, if you are implementing **OntimizeEE**, to complete the steps you need to perform on your backend server to complete the report store configuration following this [link](https://ontimize.github.io/ontimize-boot/basics/reports/report-store){:target="_blank"} + {: .note} ->Remember to complete the steps you need to perform on your backend server to complete the report store configuration following this [link](https://ontimize.github.io/ontimize-boot/basics/reports/report-store){:target="_blank"} +>Additionally, if you are implementing **JSON:API**, ensure your backend is configured accordingly by following the guidelines provided [here]({{ base_path }}/jsonapi){:target="_blank"} To add that in your application run a reports with jasper template you have to follow the following steps +1. To configure the report store service, you can configure the path in `servicesConfiguration`. +The default path for requests to +* **OntimizeEE** is `/reportstore` , +* **JSON:API** is `/Report` . + +```ts +export const SERVICE_CONFIG = +{ + 'reportoarameter': { + 'path': '/ReportParameter' + }, + 'reportstore': { + 'path': '/Report' + }, + ... +} +``` -1. To add new menu option `Reports` in `src/app/shared/app.menu.config.ts` +2. To add new menu option `Reports` in `src/app/shared/app.menu.config.ts` ```ts .. @@ -32,7 +54,7 @@ To add that in your application run a reports with jasper template you have to f } ``` -2. In `src/app/main/main-routing.module.ts`, add a route for new report management module p.e with `path` of `reports` +3. In `src/app/main/main-routing.module.ts`, add a route for new report management module p.e with `path` of `reports` ```ts import { NgModule } from '@angular/core'; @@ -58,7 +80,7 @@ To add that in your application run a reports with jasper template you have to f export class MainRoutingModule { } ``` -3. Create the new report management module `ReportModule` and import `OReportRoutingModule` module +4. Create the new report management module `ReportModule` and import `OReportRoutingModule` module ```ts import { NgModule } from '@angular/core'; @@ -78,7 +100,7 @@ To add that in your application run a reports with jasper template you have to f export class ReportModule{} ``` -4. To add/remove/update report +5. To add/remove/update report Now you should a new option similar to where you can management the reports @@ -92,7 +114,7 @@ To add that in your application run a reports with jasper template you have to f ![Detail report ]({{ "/assets/images/report/reportDetailStore.png" | absolute_url }}){: .comp-example-img} -5. Add a button and on its click event generate the PDF document. The method `openFillReport` takes as parameter the `UUID`, the parameters values and the filter of the report. +6. Add a button and on its click event generate the PDF document. The method `openFillReport` takes as parameter the `UUID`, the parameters values and the filter of the report. ```html diff --git a/docs/guide/10-structure.md b/docs/guide/10-structure.md index ccd83964b..018fbfdc5 100644 --- a/docs/guide/10-structure.md +++ b/docs/guide/10-structure.md @@ -57,7 +57,7 @@ ontimize-web-ngx-quickstart | | | ├── movement-types-renderer/ # Custom component (cell renderer) definition | | | |── style-manager/ # Class for managing stylesheets | | | |── app.menu.config.ts # Application menu definition -| | | |── app.services.config.ts # Ontimize JEE services path configuration file +| | | |── app.services.config.ts # Ontimize JEE or JSON:API services path configuration file | | | |── constant.ts # File used to store constant variables on the app like the primary color code | | | └── shared.modules.ts # Shared module definition | | | diff --git a/docs/guide/11-app-config.md b/docs/guide/11-app-config.md index 330b88c0b..378c010e9 100644 --- a/docs/guide/11-app-config.md +++ b/docs/guide/11-app-config.md @@ -29,7 +29,7 @@ export const CONFIG: Config = { uuid: 'com.ontimize.web.quickstart', title: 'Ontimize Web QuickStart', locale: 'es', /* Optional */ - serviceType: 'Ontimize' | 'OntimizeEE',/* Optional */ + serviceType: 'Ontimize' | 'OntimizeEE' | 'JSONAPI',/* Optional, by default is OntimizeEE */ servicesConfiguration: SERVICE_CONFIG, appMenuConfiguration: MENU_CONFIG, applicationLocales: ['es', 'en'], @@ -55,7 +55,8 @@ export const CONFIG: Config = { }, exportConfiguration: { path:'/export' - } + }, + nameConvention: 'upper' | 'lower' | 'database' /* Optional */ }; ``` {: .no-scroll} @@ -66,11 +67,12 @@ The noteworthy parameters here are: - **uuid:** The application identifier, this is the unique package identifier of the application. It is used when storing or managing temporal data related with the application. By default is set as `ontimize-web-uuid`. - **title:** The title of the application. - **locale:** The language of the application specified by the country code (e.g. 'es' for Spanish, 'en' for English, etc.). -- **serviceType:** The service type used in the app by framework components that request data from server. You can specify Ontimize REST standard, Ontimize REST JEE or a custom implementation. - - **Not configured (by default):** if you do not configure or specify this parameter, the framework configures Ontimize REST standard services. - - **'Ontimize'(default):** string that configures Ontimize REST services. - - **'OntimizeEE':** string that configures Ontimize REST JEE services and is the default value. - - **Custom class:** a service class reference that extends `OntimizeService` or `OntimizeEEService` or implements the `IDataService` interface. More information [here]({{ base_path }}/guide/service/#extending-ontimize-web-services){:target="_blank"}. +- **serviceType:** The service type used in the app by framework components that request data from server. You can specify Ontimize REST standard, Ontimize REST JEE, JSON:API standard or a custom implementation. + - **Not configured (by default):** if you do not configure or specify this parameter, the framework configures OntimizeEE REST standard services. + - **'Ontimize'** string that configures Ontimize REST services. + - **'OntimizeEE'(default)::** string that configures Ontimize REST JEE services and is the default value. + - **'JSONAPI':** string that configures JSON:API REST services + - **Custom class:** a service class reference that extends `OntimizeService`, `OntimizeEEService`, `JSONAPI` or implements the `IDataService` interface. More information [here]({{ base_path }}/guide/service/#extending-ontimize-web-services){:target="_blank"}. - **servicesConfiguration:** Object that contains the services configuration parameters. Learn more [here](#services-configuration). - **appMenuConfiguration:** Object defining application menu structure. Learn more [here](#menu-configuration). - **applicationLocales:** Set of available locales for the application. @@ -94,6 +96,11 @@ The noteworthy parameters here are: - **permissionsConfiguration:** permissions service configuration object. - **exportConfiguration**: export configuration object required only with `Ontimize Boot version 3.9.0 or above` - **path**: the export path used in the remote package query compatible. +- **nameConvention**: Indicates the naming format to which database column names will be transformed when exposed through REST API requests. + Column names will be converted to `upper`,`lower` or `database` + - `upper`: All letters in column names will be converted to uppercase (e.g., `USER_ID`). + - `lower`: All letters in column names will be converted to lowercase (e.g., `user_id`). + - `database`: Column names will be used as defined in the component configuration, without any transformation (e.g., `UserId` or `USER_ID`, depending on how they are stored). # Package.json configuration @@ -311,12 +318,15 @@ You have to replace the references of "ontimize-web-ngx-jee-seed" by the name of # Services configuration -If you indicate in the application configuration that the application should use **OntimizeEE** services (check `serviceType` attribute in the [previous section](#application-configuration-file) of this page), you have to configure the service paths. For doing this **OntimizeWeb** uses the `servicesConfiguration` property from the app configuration file that must point to an object defined as in the example below. +Ontimize Web supports **OntimizeEE** and **JSON:API**, to configure this standards you need to specify it in the `servicesConfiguration` (check `serviceType` attribute in the [previous section](#application-configuration-file). + of this page). + + If you indicate in the application configuration that the application should use **OntimizeEE** or **JSON:API** services, you have to configure the service paths. For doing this **OntimizeWeb** uses the `servicesConfiguration` property from the app configuration file which should reference an object structured as shown in the example below. -In this object, the keys represents the different services names used in the application. Every service needs a `path` property where you must set the path of the service, excluding the URL configured in the `apiEndpoint` attribute of the application configuration. +In this object, each key represents a different service used in the application. Each service must include a `path` property, where you define the service's path—excluding the base URL specified in the apiEndpoint attribute of the application configuration. ```javascript -export const SERVICE_CONFIG: Object = { +export const SERVICE_CONFIG = { 'users': { 'path': '/users' }, @@ -338,7 +348,7 @@ export const SERVICE_CONFIG: Object = { }; ``` -For clarification, if your `apiEndpoint` is the one in the [application configuration](#application-configuration-file) example, **OntimizeWeb** will concat the `apiEndpoint` and the `path` of the service to build the URL for sending requests. For example : https://try.ontimize.com/QSAllComponents-jee/services/rest/customers. +For clarification, if your `apiEndpoint` is the one in the [application configuration](#application-configuration-file) example, **OntimizeWeb** and **JSON:API** will concat the `apiEndpoint` and the `path` of the service to build the URL for sending requests. For example : https://try.ontimize.com/QSAllComponents-jee/services/rest/customers. # Internationalization (i18) configuration diff --git a/docs/guide/15-service.md b/docs/guide/15-service.md index 95a63a92f..f46250c1d 100644 --- a/docs/guide/15-service.md +++ b/docs/guide/15-service.md @@ -1,279 +1,333 @@ --- layout: default -title: "Services" +title: Services +has_children: true permalink: /guide/service/ parent: Guide -nav_order: 6 +nav_order: 3 +has_toc: false --- {% include base_path %} {% include toc %} -This section describes the **OntimizeWeb** services an how to extend them to add or modify its functionality. +OntimizeWeb provides a powerful and flexible way to interact with backend services, supporting both **standard APIs using the JSON:API** and **Ontimize-based backends** . This allows developers to integrate data sources seamlessly using a standardized interface while maintaining the reactive and component-driven architecture of Angular. -## Ontimize services +This guide describes how services work in OntimizeWeb, how to extend them, and how to integrate third-party APIs using the JSON:API specification. Whether you're working with an Ontimize server or a modern RESTful API, this documentation will help you implement consistent data access across your application. -OntimizeWeb services are used for fetching and saving data from servers based on [Ontimize](https://github.com/ontimize){:target="_blank"}. There is two types of Ontimize services depending on the server technology used: `OntimizeService` and `OntimizeEEService`. You must indicate which type of service the application will use by configuring the `serviceType` attribute in the [application configuration]({{ base_path }}/guide/appconfig/#application-configuration-file){:target="_blank"}. -You can also use your own service and adapt its response to OntimizeWeb's standard response. This will be explained later in this section. +{% include nav_cards.html folder="services" %} -### Ontimize services methods -Both services `OntimizeService` and `OntimizeEEService` have the same methods for configuring and sending request to the server. This methods are the following: +## Extending Ontimize Web services -```javascript -/* Configuration methods */ -getDefaultServiceConfiguration(serviceName?: string): Object; -configureService(config: any): void; - -/* CRUD methods */ -query(kv?: Object, av?: Array, entity?: string, sqltypes?: Object): Observable; -advancedQuery(kv?: Object, av?: Array, entity?: string, sqltypes?: object, - offset?: number, pagesize?: number, orderby?: Array): Observable -insert(av: Object = {}, entity: string, sqltypes?: object): Observable -update(kv: Object = {}, av: object = {}, entity?: string, sqltypes?: object): Observable -delete(kv: Object = {}, entity?: string, sqltypes?: Object): Observable - -/** -* Successful response parsers, there is one parser for each CRUD method which calls to the common parser. -* User can overwrite the chosen methods parsers or the common parser -*/ -protected parseSuccessfulResponse(resp: any, _innerObserver: any); -protected parseSuccessfulQueryResponse(resp: any, _innerObserver: any); -protected parseSuccessfulAdvancedQueryResponse(resp: any, _innerObserver: any); -protected parseSuccessfulInsertResponse(resp: any, _innerObserver: any); -protected parseSuccessfulUpdateResponse(resp: any, _innerObserver: any); -protected parseSuccessfulDeleteResponse(resp: any, _innerObserver: any); - -/** -* Unsuccessful response parsers, there is one parser for each CRUD method which calls to the common parser. -* User can overwrite the chosen methods parsers or the common parser -*/ -protected parseUnsuccessfulResponse(error: any, _innerObserver: any); -protected parseUnsuccessfulQueryResponse(resp: any, _innerObserver: any); -protected parseUnsuccessfulAdvancedQueryResponse(resp: any, _innerObserver: any); -protected parseUnsuccessfulInsertResponse(resp: any, _innerObserver: any); -protected parseUnsuccessfulUpdateResponse(resp: any, _innerObserver: any); -protected parseUnsuccessfulDeleteResponse(resp: any, _innerObserver: any); - -/* Authentication methods */ -startsession(user: string, password: string): Observable; -endsession(user: string, sessionId: number): Observable; -redirectLogin?(sessionExpired?: boolean); -``` +You can override or extend the functionality of the services defined in **OntimizeWeb**. You should know that some services are used internally and they cannot be extended. The prepared-to-extend services are the following: +| Service | Injection token | Description | +| ----------------------------------------------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `OntimizeService`, `OntimizeEEService` or `JSONAPIService`(since *ontimize-web-ngx@15.6.0*) | `O_DATA_SERVICE` | Service used for making CRUD operation and authentication | +| `OTranslateService` | `O_TRANSLATE_SERVICE` | Service for translating the information shown in the application | +| `OntimizeFileService` | `O_FILE_SERVICE` | Service for uploading files, used by the [`o-file-input`]({{ base_path }}/components/input/file/overview){:target="\_blank"} component | +| `OntimizeExportService` and `OntimizeExportService3X` | `O_EXPORT_SERVICE` | Service used by the [`o-table`]({{ base_path }}/components/data/table/overview){:target="\_blank"} component for exporting its data | +| `OntimizePermissionsService` and `OntimizeEEPermissionsService` | `O_PERMISSION_SERVICE` | Service used for loading the application permissions | +| `AuthService` | `O_AUTH_SERVICE` | Service used for authentication (since *ontimize-web-ngx@8.3.0*) | +| `OReportService` or `JSONAPIReportService` (since *ontimize-web-ngx-report@15.2.0) | `O_REPORT_SERVICE` | Service used to generate reports (since *ontimize-web-ngx@8.7.0*) | +| `OntimizeExportDataProviderService` and `OntimizeExportDataProviderService3X` | `O_EXPORT_DATA_SERVICE` | Service used to provide data and styles to table exports (since *ontimize-web-ngx@8.8.0*) | +| `OTableGlobalConfig` | `O_TABLE_GLOBAL_CONFIG` | Service used to set some [`o-table`]({{ base_path }}/components/data/table/overview){:target="\_blank"} global options (since *ontimize-web-ngx@8.7.3*) | +| `LocalStorageService` | `O_LOCALSTORAGE_SERVICE` | Service used to save in application data in local storage (since *ontimize-web-ngx@15.2.0*) | -### CRUD methods -The *CRUD* (Create, Read, Update and Delete) methods are used to perform standard Ontimize operations: - -* **query**: performs a request to get data from the server. - * **kv**: indicates the filtering values. An empty object means that no filter will be applied into the request. - * **av**: indicates the columns that you want to request. - * **entity**: indicates the entity to perform the request. - * **sqltypes**: object with the data types for each colum that participates in the request according to Java standard (see [SQLType](https://github.com/OntimizeWeb/ontimize-web-ngx/blob/15.x.x/projects/ontimize-web-ngx/src/lib/util/sqltypes.ts){:target='_blank'}). -* **advancedQuery**: performs a request to get **paginated** data from the server. - * **kv**: indicates the filtering values. An empty object means that no filter will be applied into the request. - * **av**: indicates the columns that you want to request. - * **entity**: indicates the entity to perform the request. - * **sqltypes**: object with the data types for each colum that participates in the request according to Java standard (see [SQLType](https://github.com/OntimizeWeb/ontimize-web-ngx/blob/15.x.x/projects/ontimize-web-ngx/src/lib/util/sqltypes.ts){:target='_blank'}). - * **offset**: the index of the first item requested in the collection. - * **pagesize**: the number of items requested. - * **orderby**: object with the sorting that will be applied to the request result. -* **insert**: performs a insert operation request to the server. - * **av**: indicates the values to insert. - * **entity**: indicates the entity to perform the request. - * **sqltypes**: object with the data types for each colum that participates in the request according to Java standard (see [SQLType](https://github.com/OntimizeWeb/ontimize-web-ngx/blob/15.x.x/projects/ontimize-web-ngx/src/lib/util/sqltypes.ts){:target='_blank'}). -* **update**: performs an update operation request to the server. - * **kv**: indicates the filtering values for performing the update. - * **av**: indicates the values to update. - * **entity**: indicates the entity to perform the request. - * **sqltypes**: object with the data types for each colum that participates in the request according to Java standard (see [SQLType](https://github.com/OntimizeWeb/ontimize-web-ngx/blob/15.x.x/projects/ontimize-web-ngx/src/lib/util/sqltypes.ts){:target='_blank'}). -* **delete**: performs an delete operation request to the server. - * **kv**: indicates the filtering values for performing the deletion. - * **entity**: indicates the entity to perform the request. - * **sqltypes**: object with the data types for each colum that participates in the request according to Java standard (see [SQLType](https://github.com/OntimizeWeb/ontimize-web-ngx/blob/15.x.x/projects/ontimize-web-ngx/src/lib/util/sqltypes.ts){:target='_blank'}). - -### Server response interface -The standard response of the requests made to Ontimize based servers always follows the following structure: +For extending a service you should create your own service that extends a service from **OntimizeWeb** and provide it in your application using the corresponding injection token from the table above. -```javascript -{ - code: number; - data: Array; - message: ''; - sqlTypes?: Object; - startRecordIndex?: number; - totalQueryRecordsNumber?: number; -} + +### Create and extend a service new + +In Ontimize Web, services act as the bridge between UI components and backend APIs or external data sources. Creating and extending a service allows you to customize how data is requested, filtered, and processed to suit your specific backend requirements or third-party APIs. + +To implement a service, you typically define: + +* How query parameters from UI filters are adapted to the backend’s expected format (**Request Arguments Adapter**). +* How the backend’s response is converted into a structure that Ontimize can work with (**Response Adapter**). +* The main service class that manages data operations (query, insert, update, delete) using the above adapters (**Custom Service**). + + +| Component | Purpose | +| ----------------------------- | --------------------------------------------------------------------------------------- | +| **Custom Service** | Extends `BaseDataService`; manages data requests and responses. | +| **Request Arguments Adapter** | Converts Ontimize filters and query parameters to backend format. | +| **Response Adapter** | Transforms backend API responses into Ontimize-compatible format. | +| **Service Response Class** | Defines the structure of the response, mapping backend fields to Ontimize expectations. | + + +#### Component Interaction Diagram + +```plaintext + ┌─────────────────────────────┐ + │ Ontimize UI Components │ + │ (o-table, o-form, etc.) │ + └─────────────┬───────────────┘ + │ + ▼ + ┌─────────────────────────────┐ + │ Custom Data Service │ + │ (extends BaseDataService) │ + │ - Coordinates request │ + │ - Uses Request Arguments │ + │ Adapter to prepare params │ + │ - Uses Response Adapter │ + └─────┬────────────┬──────────┘ + │ │ + ▼ ▼ + ┌─────────────┐ ┌───────────────────────────┐ + │ RequestArgs │ │ Response Adapter │ + │ Adapter │ │ - Converts API responses │ + │ - Transforms│ │ to Ontimize format │ + │ filters │ └───────────────────────────┘ + └─────────────┘ + │ + ▼ + ┌─────────────────────────┐ + │ Backend / External API │ + │ (RESTful service) │ + └─────────────────────────┘ ``` -Where the attributes indicates the following: +**How it works:** -* **code**: indicates the result of the operation: 0 for successful operations, 1 for unsuccessful operations, 3 for session expired. -* **data**: the data requested. -* **message**: a message in case the response was not successful. -* **sqlTypes**: indicates the data type according to Java standard. See [SQL Types](https://docs.oracle.com/javase/8/docs/api/java/sql/Types.html){:target='_blank'}. -* **startRecordIndex**: in paginated queries, indicates the position of the first retrieved record in the collection. -* **totalQueryRecordsNumber**: in paginated queries, indicates the total number of record of the collection. +1. UI components trigger data operations through the custom service. +2. The service adapts Ontimize filters into backend query parameters using the Request Arguments Adapter. +3. It sends the HTTP request to the backend API. +4. Upon response, the Response Adapter transforms the raw data into Ontimize-compatible responses. +5. The processed data is returned to UI components. -You can see an example of a Ontimize service request response in the image below. You can see the complete response [here]({{ base_path }}/assets/examples/ontimize_service_request_example_response.json){:target='_blank'}. -![Ontimize service response example]({{ base_path }}/assets/images/request.png){: .align-center} +#### Example: Rick and Morty API Integration -### Use OntimizeService in your application +Below is an example of how these components come together for integrating with the Rick and Morty API. The custom service handles queries, uses adapters for requests and responses, and manages data transformation seamlessly. -Check the example below about how to configure and use the `OntimizeService` for querying data in your application. -```javascript -protected service: OntimizeService; +##### 1. Create a Custom Service -constructor(protected injector: Injector) { - this.service = this.injector.get(OntimizeService); -} +To create a custom service in Ontimize Web, extend the BaseDataService class, specifying the type of data your service will handle. This service will manage how data operations such as querying or updating are performed against your backend or external API. -ngOnInit() { - this.configureService(); -} +Within your service: -protected configureService() { - // Configure the service using the configuration defined in the `app.services.config.ts` file - const conf = this.service.getDefaultServiceConfiguration('movements'); - this.service.configureService(conf); -} +- Use the constructor to inject dependencies and set up any adapters needed to transform requests and responses. -getMovements(data) { - if (data.hasOwnProperty('ACCOUNTID') && this.service !== null) { - const filter = { - 'ACCOUNTID': data['ACCOUNTID'] - }; - const columns = [this.yAxis, this.xAxis, 'DATE_']; - this.service.query(filter, columns, 'movement').subscribe(resp => { - if (resp.code === 0) { +- Override configuration methods like configureService and configureAdapter to define API paths and specify the adapters your service uses. - // resp.data contains the data retrieved from the server +- Implement or override data operation methods like query to customize how requests are constructed and sent. - } else { - alert('Impossible to query data!'); - } - }); +- Optionally, implement other CRUD methods (insert, update, delete) depending on your backend capabilities. + +```ts +@Injectable() +export class RickAndMortyService extends BaseDataService { + + constructor(injector: Injector) { + super(injector); + this.requestArgumentAdapter = this.injector.get(RickAndMortyRequestArgumentsAdapter); } -``` -## Extending Ontimize Web services + public configureService(config: any): void { + super.configureService(config); + this.path = config.path; + } -You can override or extend the functionality of the services defined in **OntimizeWeb**. You should know that some services are used internally and they cannot be extended. The prepared-to-extend services are the following: + public configureAdapter() { + this.adapter = this.injector.get(RickAndMortyResponseAdapter); + } -| Service | Injection token | Description | -| ------- | ------- | ------- | -| `OntimizeService` and `OntimizeEEService` | `O_DATA_SERVICE` | Service used for making CRUD operation and authentication | -| `OTranslateService` | `O_TRANSLATE_SERVICE` | Service for translating the information shown in the application | -| `OntimizeFileService` | `O_FILE_SERVICE` | Service for uploading files, used by the [`o-file-input`]({{ base_path }}/components/input/file/overview){:target="_blank"} component | -| `OntimizeExportService` and `OntimizeExportService3X` | `O_EXPORT_SERVICE` | Service used by the [`o-table`]({{ base_path }}/components/data/table/overview){:target="_blank"} component for exporting its data | -| `OntimizePermissionsService` and `OntimizeEEPermissionsService` | `O_PERMISSION_SERVICE` | Service used for loading the application permissions | -| `AuthService` | `O_AUTH_SERVICE` | Service used for authentication (since *ontimize-web-ngx@8.3.0*) | -| `OReportService` | `O_REPORT_SERVICE` | Service used to generate reports (since *ontimize-web-ngx@8.7.0*) | -| `OntimizeExportDataProviderService` and `OntimizeExportDataProviderService3X` | `O_EXPORT_DATA_SERVICE` | Service used to provide data and styles to table exports (since *ontimize-web-ngx@8.8.0*) | -| `OTableGlobalConfig` | `O_TABLE_GLOBAL_CONFIG` | Service used to set some [`o-table`]({{ base_path }}/components/data/table/overview){:target="_blank"} global options (since *ontimize-web-ngx@8.7.3*) | -| `LocalStorageService` | `O_LOCALSTORAGE_SERVICE` | Service used to save in application data in local storage (since *ontimize-web-ngx@15.2.0*) | + query(...args: [any, ...any[]]): Observable { + const [filter] = args[0]; + const page = this.getPaginationContext().pageNumber ?? 0; + const queryParams = this.toQueryParams(filter); + const url = `${this.urlBase}${this.path}${queryParams}&page=${page}`; + return this.doRequest({ + method: 'GET', + url: url, + options: {} // optional: can include headers or credentials if needed + }); + } -For extending a service you should create your own service that extends a service from **OntimizeWeb** and provide it in your application using the corresponding injection token from the table above. + advancedQuery(...args: [any, ...any[]]): Observable { + return this.query(args); + } -### Create and extend a service + // You can implement insert/update/delete if needed + insert(): Observable { + throw new Error('Method not implemented.'); + } -Create a new service class that extends a service from **OntimizeWeb**. In the following example we are creating a service called `StarWarsService` that extends the class `OntimizeBaseService` (`OntimizeBaseService` is the super class for different services in **OntimizeWeb**). + update(): Observable { + throw new Error('Method not implemented.'); + } -```javascript -import { Injectable, Injector } from '@angular/core'; + delete(): Observable { + throw new Error('Method not implemented.'); + } -import { OntimizeBaseService } from 'ontimize-web-ngx'; + /** + * Converts a filter object into a query parameter string. + */ + public toQueryParams(obj: Record): string { + const params = Object.entries(obj) + .filter(([_, value]) => !!value) + .map(([key, value]) => { + const cleanValue = value.replace(/%/g, ''); + return `${encodeURIComponent(key)}=${encodeURIComponent(cleanValue)}`; + }) + .join('&'); + return `?${params}`; + } +} +``` + +--- +##### 2. Create a Request Adapter + +This adapter is responsible for converting Ontimize filter expressions into key-value pairs that can be used as query parameters in your API. + +```ts @Injectable() -export class StarWarsService extends OntimizeBaseService { +export class RickAndMortyRequestArgumentsAdapter extends BaseRequestArgument { + parseQueryParameters(params: any) { + const { filter, columns } = params; + const parsedFilter = this.deCompose(filter, columns, {}); + return [parsedFilter, columns, params.entity, params.sqlTypes]; + } - constructor(protected injector: Injector) { - super(injector); + deCompose(expression, columns: Array, kv: Object) { + const basic = expression[FilterExpressionUtils.BASIC_EXPRESSION_KEY]; + const filter = expression[FilterExpressionUtils.FILTER_EXPRESSION_KEY]; + + if (Util.isDefined(basic)) { + kv = this.deComposeExpresion(basic, columns, kv); + } + + if (Util.isDefined(filter)) { + kv = this.deComposeExpresion(filter, columns, kv); + } + + return kv; } + deComposeExpresion(expr: any, columns: Array, kv: Object) { + if (FilterExpressionUtils.instanceofExpression(expr)) { + if (typeof expr.lop !== 'string') { + kv = this.deComposeExpresion(expr.lop, columns, kv); + return this.deComposeExpresion(expr.rop, columns, kv); + } else { + return { ...kv, [expr.lop]: expr.rop }; + } + } + } } ``` -Once your service is created you can [override the Ontimize CRUD methods](#override-crud-methods-using-a-third-party-api) and/or [define new methods](#define-your-own-crud-methods). After that you must decide if the service will be used [in the whole application](#use-your-service-in-the-whole-application) or only in [specific components](#use-your-service-in-a-specific-component). +--- -### Override CRUD methods using a third party API +##### 3. Create a Response Adapter -You can use your service to retrieve or send data to a third party API. The following example shows the service from the previous step consuming the [Star Wars API](https://swapi.dev/){:target="_blank"} for querying different entities. We have overridden the `query` and `advancedQuery` methods for making simple and paginated request to the API. Note that you must [adapt the API response](#adapt-your-service-response) to the ontimize service response for using the retrieved data with the **OntimizeWeb** components. - -```javascript -import { Injectable, Injector } from '@angular/core'; -import { Observable, OntimizeBaseService, Util } from 'ontimize-web-ngx'; +This adapter transforms the API response into a structure compatible with Ontimize’s expectations. +```ts @Injectable() -export class StarWarsService extends OntimizeBaseService { - - constructor(protected injector: Injector) { - super(injector); +export class RickAndMortyResponseAdapter implements IServiceResponseAdapter { + adapt(resp: HttpResponse): RickAndMortyServiceResponse { + return new RickAndMortyServiceResponse( + resp.status, + resp.statusText, + resp.headers, + resp.ok, + resp.body + ); } - public query(kv?: Object, av?: Array, entity?: string, sqltypes?: Object): Observable { - const url = 'https://swapi.dev/api/' + entity + '/?format=json'; - - return this.doRequest({ - method: 'GET', - url: url, - options: {} // This overrides the default http headers. Remove it if you are using an ontimize based API in the backend - }); + adaptError(httpError: HttpErrorResponse) { + return httpError.error.error; } +} +``` - public advancedQuery(kv?: Object, av?: Array, entity?: string, sqltypes?: Object, offset?: number, pagesize?: number, orderby?: Array): Observable { - offset = (Util.isDefined(offset)) ? offset : this.offset; +--- - // Calculate page - let page = 0; - if (Util.isDefined(offset)) { - page = Math.trunc(offset / 10) + 1; - } +##### 4. Create a Custom Service Response + +This class maps the external API's structure to Ontimize's expected `ServiceResponse` format. + +```ts +export class RickAndMortyServiceResponse implements ServiceResponse { + public code: number; + public message: string; + public data: any; + public totalQueryRecordsNumber: number; + public startRecordIndex: number = 0; + + constructor( + public status: number, + public statusText: string, + public headers: HttpHeaders, + public ok: boolean, + public body: any + ) { + this.data = body.results || []; + this.totalQueryRecordsNumber = body.info?.count || this.data.length; + + this.code = (status >= 200 && status < 300) ? 0 : (status === 404 ? 3 : 1); + this.message = statusText; + } - let url = 'https://swapi.dev/api/' + entity + '/?format=json' + '&page=' + page; + isSuccessful(): boolean { + return this.status >= 200 && this.status < 300; + } - return this.doRequest({ - method: 'GET', - url: url, - options: {} // This overrides the default http headers. Remove it if you are using an ontimize based API in the backend - }); + isFailed(): boolean { + return this.status > 300; } + isUnauthorized(): boolean { + return this.status === 403; + } } ``` -#### doRequest method -This `doRequest` method is used to retrieve data from a URL. You can use this method with parameters to configurate the request. -You can check the options available in this example: +--- + +#### 5. Final Integration + +Once your service and adapters are ready: + +* Register the service and adapters in your Angular module's `providers` array. +```ts +@NgModule({ + declarations: [ + AppComponent, + ], + imports: [ + BrowserModule, + BrowserAnimationsModule, + OntimizeWebModule, + AppRoutingModule + ], + providers: [ + ... + { provide: 'rickandmorty', useValue: RickAndMortyService }, + RickAndMortyResponseAdapter, + RickAndMortyRequestArgumentsAdapter, + ... + ], + bootstrap: [AppComponent] +}) +* Use the service in your components or link it to a data component (like `o-table`, `o-form`, etc.) via the `serviceType` and `entity` attributes. + -```javascript -export type ServiceRequestParam = { - method: 'GET' | 'POST' | 'PUT' | 'DELETE', - url: string, - body?: any, - options?: HttpRequestOptions, - successCallback?: (resp: ServiceResponse, observer: Subscriber) => void, - errorCallBack?: (resp: ServiceResponse, observer: Subscriber) => void -}; - -// this.doRequest(ServiceRequestParam) -return this.doRequest({ - method: 'GET', - url: url, - options: {} // This overrides the default http headers. Remove it if you are using an ontimize based API in the backend -}); -``` -{: .note } ->In most cases the third party API won't offer the same response as OntimizeWeb components need so you have to [adapt the response](#adapt-your-service-response). ### Define your own CRUD methods -All the **OntimizeWeb** components that use services for retrieving data have the attributes `query-method`, `paginated-query-method`, `insert-method`, `update-method` and `deleted-method`. The purpose of these attributes is allowing the component to use your own CRUD methods defined in your service. With this you can define, for example, as many *query* methods as you want. +All the **OntimizeWeb** components that use services for retrieving data have the attributes `query-method`, `paginated-query-method`, `insert-method`, `update-method` and `deleted-method`. The purpose of these attributes is allowing the component to use your own CRUD methods defined in your service. With this you can define, for example, as many _query_ methods as you want. In the example below we have defined the `getSkywalker` method that retrieves information from the API. @@ -299,9 +353,10 @@ export class StarWarsService extends OntimizeBaseService { } ``` -Now you can configure a component from **OntimizeWeb** to use your method. Read more about this in the section [*Use your service in a specific component*](#use-your-service-in-a-specific-component). +Now you can configure a component from **OntimizeWeb** to use your method. Read more about this in the section [_Use your service in a specific component_](#use-your-service-in-a-specific-component). {: .note } + > In most cases the third party API won't offer the same response as OntimizeWeb components need so you have to [addapt the response](#adapt-your-service-response). ### Adapt your service response @@ -382,6 +437,7 @@ export class StarWarsService extends OntimizeBaseService { After this, your adapter will be called every time your service receives a response. You can also extend the `BaseServiceResponse` according to your needs. Just remember to respect this three methods that are used internally in **OntimizeWeb**: + - isSuccessful() - isFailed() - isUnauthorized() @@ -404,11 +460,12 @@ export class AppModule { } At this point every **OntimizeWeb** component will use your recently created `StarWarsService` service for communicating with the backend. {: .note } -> `OntimizeService`, `OntimizeEEService`, `OntimizeExportService`, `OntimizePermissionsService` and `OntimizeEEPermissionsService` can be extended and used in the whole application by indicating the class in the [application configuration]({{ base_path }}/guide/appconfig/#application-configuration-file){:target="_blank"}. There is one attribute for each type of service. + +> `OntimizeService`, `OntimizeEEService`, `OntimizeExportService`, `OntimizePermissionsService` and `OntimizeEEPermissionsService` can be extended and used in the whole application by indicating the class in the [application configuration]({{ base_path }}/guide/appconfig/#application-configuration-file){:target="\_blank"}. There is one attribute for each type of service. ### Use your service in a specific component -If you want to use your service in a specific component instead of using it in the whole application, you have to create a provide method that returns a new instance of your service and add a provider to your module indicating the factory method like in the example below. +If you want to use your service in a specific component instead of using it in the whole application, you have to create a provide method that returns a new instance of your service and add a provider to your module indicating the factory method like in the example below. ```javascript import { StarWarsService } from '../../shared/star-wars.service'; @@ -428,14 +485,19 @@ export class MyModule { } Once the service is included in the providers of your module, it will be created an instance of the service for each component. For this, configure the `service-type` attribute in the component with the value of the `provide` attribute indicated in the previous step. Check the example below. - ```html - - + ... - ``` @@ -443,4 +505,6 @@ Once the service is included in the providers of your module, it will be created **OntimizeWeb** defines a successful and unsuccessful request callbacks for each CRUD method, this methods are called when the service receives the response from the API. You can override this methods in order to modify its behaviour. This methods are: `parseSuccessfulMETHODResponse` and `parseUnsuccessfulMETHODResponse` where `METHOD` is `query`, `advancedQuery`, `update`, `insert` or `delete`. -Both services `OntimizeService` and `OntimizeEEService` also have a generic succesful and unsuccessful request callback which are `parseSuccessfulResponse` and `parseUnsuccessfulResponse`. This callbacks are called from the previous explained CRUD method callbacks so user can choose whether to override a particular or the generic method. +The service `JSONAPIService` has a generic succesful and unsuccessful request callback which are `parseSuccessfulResponse` and `parseUnsuccessfulResponse`. This callbacks are called from the previous explained CRUD method callbacks so user can choose whether to override a particular or the generic method. + + diff --git a/docs/guide/services/15d-ontimize.md b/docs/guide/services/15d-ontimize.md new file mode 100644 index 000000000..23e964de3 --- /dev/null +++ b/docs/guide/services/15d-ontimize.md @@ -0,0 +1,159 @@ +--- +layout: default +title: "Ontimize Web" +permalink: /guide/service/ontimize +parent: Services +grand_parent: Guide +nav_order: 2 +--- + +{% include base_path %} +{% include toc %} + +This section describes the **OntimizeWeb** services an how to extend them to add or modify its functionality. + +OntimizeWeb services are used for fetching and saving data from servers based on [Ontimize](https://github.com/ontimize){:target="_blank"}. There is two types of Ontimize services depending on the server technology used: `OntimizeService` and `OntimizeEEService`. You must indicate which type of service the application will use by configuring the `serviceType` attribute in the [application configuration]({{ base_path }}/guide/appconfig/#application-configuration-file){:target="_blank"}. + +You can also use your own service and adapt its response to OntimizeWeb's standard response. This will be explained later in this section. + +### Ontimize services methods + +Both services `OntimizeService` and `OntimizeEEService` have the same methods for configuring and sending request to the server. This methods are the following: + +```javascript +/* Configuration methods */ +getDefaultServiceConfiguration(serviceName?: string): Object; +configureService(config: any): void; + +/* CRUD methods */ +query(kv?: Object, av?: Array, entity?: string, sqltypes?: Object): Observable; +advancedQuery(kv?: Object, av?: Array, entity?: string, sqltypes?: object, + offset?: number, pagesize?: number, orderby?: Array): Observable +insert(av: Object = {}, entity: string, sqltypes?: object): Observable +update(kv: Object = {}, av: object = {}, entity?: string, sqltypes?: object): Observable +delete(kv: Object = {}, entity?: string, sqltypes?: Object): Observable + +/** +* Successful response parsers, there is one parser for each CRUD method which calls to the common parser. +* User can overwrite the chosen methods parsers or the common parser +*/ +protected parseSuccessfulResponse(resp: any, _innerObserver: any); +protected parseSuccessfulQueryResponse(resp: any, _innerObserver: any); +protected parseSuccessfulAdvancedQueryResponse(resp: any, _innerObserver: any); +protected parseSuccessfulInsertResponse(resp: any, _innerObserver: any); +protected parseSuccessfulUpdateResponse(resp: any, _innerObserver: any); +protected parseSuccessfulDeleteResponse(resp: any, _innerObserver: any); + +/** +* Unsuccessful response parsers, there is one parser for each CRUD method which calls to the common parser. +* User can overwrite the chosen methods parsers or the common parser +*/ +protected parseUnsuccessfulResponse(error: any, _innerObserver: any); +protected parseUnsuccessfulQueryResponse(resp: any, _innerObserver: any); +protected parseUnsuccessfulAdvancedQueryResponse(resp: any, _innerObserver: any); +protected parseUnsuccessfulInsertResponse(resp: any, _innerObserver: any); +protected parseUnsuccessfulUpdateResponse(resp: any, _innerObserver: any); +protected parseUnsuccessfulDeleteResponse(resp: any, _innerObserver: any); + +/* Authentication methods */ +startsession(user: string, password: string): Observable; +endsession(user: string, sessionId: number): Observable; +redirectLogin?(sessionExpired?: boolean); +``` + + +### CRUD methods +The *CRUD* (Create, Read, Update and Delete) methods are used to perform standard Ontimize operations: + +* **query**: performs a request to get data from the server. + * **kv**: indicates the filtering values. An empty object means that no filter will be applied into the request. + * **av**: indicates the columns that you want to request. + * **entity**: indicates the entity to perform the request. + * **sqltypes**: object with the data types for each colum that participates in the request according to Java standard (see [SQLType](https://github.com/OntimizeWeb/ontimize-web-ngx/blob/15.x.x/projects/ontimize-web-ngx/src/lib/util/sqltypes.ts){:target='_blank'}). +* **advancedQuery**: performs a request to get **paginated** data from the server. + * **kv**: indicates the filtering values. An empty object means that no filter will be applied into the request. + * **av**: indicates the columns that you want to request. + * **entity**: indicates the entity to perform the request. + * **sqltypes**: object with the data types for each colum that participates in the request according to Java standard (see [SQLType](https://github.com/OntimizeWeb/ontimize-web-ngx/blob/15.x.x/projects/ontimize-web-ngx/src/lib/util/sqltypes.ts){:target='_blank'}). + * **offset**: the index of the first item requested in the collection. + * **pagesize**: the number of items requested. + * **orderby**: object with the sorting that will be applied to the request result. +* **insert**: performs a insert operation request to the server. + * **av**: indicates the values to insert. + * **entity**: indicates the entity to perform the request. + * **sqltypes**: object with the data types for each colum that participates in the request according to Java standard (see [SQLType](https://github.com/OntimizeWeb/ontimize-web-ngx/blob/15.x.x/projects/ontimize-web-ngx/src/lib/util/sqltypes.ts){:target='_blank'}). +* **update**: performs an update operation request to the server. + * **kv**: indicates the filtering values for performing the update. + * **av**: indicates the values to update. + * **entity**: indicates the entity to perform the request. + * **sqltypes**: object with the data types for each colum that participates in the request according to Java standard (see [SQLType](https://github.com/OntimizeWeb/ontimize-web-ngx/blob/15.x.x/projects/ontimize-web-ngx/src/lib/util/sqltypes.ts){:target='_blank'}). +* **delete**: performs an delete operation request to the server. + * **kv**: indicates the filtering values for performing the deletion. + * **entity**: indicates the entity to perform the request. + * **sqltypes**: object with the data types for each colum that participates in the request according to Java standard (see [SQLType](https://github.com/OntimizeWeb/ontimize-web-ngx/blob/15.x.x/projects/ontimize-web-ngx/src/lib/util/sqltypes.ts){:target='_blank'}). + +### Server response interface +The standard response of the requests made to Ontimize based servers always follows the following structure: + +```javascript +{ + code: number; + data: Array; + message: ''; + sqlTypes?: Object; + startRecordIndex?: number; + totalQueryRecordsNumber?: number; +} +``` + +Where the attributes indicates the following: + +* **code**: indicates the result of the operation: 0 for successful operations, 1 for unsuccessful operations, 3 for session expired. +* **data**: the data requested. +* **message**: a message in case the response was not successful. +* **sqlTypes**: indicates the data type according to Java standard. See [SQL Types](https://docs.oracle.com/javase/8/docs/api/java/sql/Types.html){:target='_blank'}. +* **startRecordIndex**: in paginated queries, indicates the position of the first retrieved record in the collection. +* **totalQueryRecordsNumber**: in paginated queries, indicates the total number of record of the collection. + +You can see an example of a Ontimize service request response in the image below. You can see the complete response [here]({{ base_path }}/assets/examples/ontimize_service_request_example_response.json){:target='_blank'}. + +![Ontimize service response example]({{ base_path }}/assets/images/request.png){: .align-center} + +### Use OntimizeService in your application + +Check the example below about how to configure and use the `OntimizeService` for querying data in your application. + +```javascript +protected service: OntimizeService; + +constructor(protected injector: Injector) { + this.service = this.injector.get(OntimizeService); +} + +ngOnInit() { + this.configureService(); +} + +protected configureService() { + // Configure the service using the configuration defined in the `app.services.config.ts` file + const conf = this.service.getDefaultServiceConfiguration('movements'); + this.service.configureService(conf); +} + +getMovements(data) { + if (data.hasOwnProperty('ACCOUNTID') && this.service !== null) { + const filter = { + 'ACCOUNTID': data['ACCOUNTID'] + }; + const columns = [this.yAxis, this.xAxis, 'DATE_']; + this.service.query(filter, columns, 'movement').subscribe(resp => { + if (resp.code === 0) { + + // resp.data contains the data retrieved from the server + + } else { + alert('Impossible to query data!'); + } + }); + } +``` diff --git a/docs/guide/services/15e-jsonapi.md b/docs/guide/services/15e-jsonapi.md new file mode 100644 index 000000000..0898d0c8a --- /dev/null +++ b/docs/guide/services/15e-jsonapi.md @@ -0,0 +1,389 @@ +--- +layout: default +title: "JSON API" +permalink: /guide/service/jsonapi +parent: Services +grand_parent: Guide +nav_order: 1 +--- + +{% include base_path %} +{% include toc %} + +> ⚠️ **Note:** This feature is available starting from version **15.6.0** of OntimizeWeb. +> Make sure your project is using this version or higher to take advantage of this functionality. + +In addition to Ontimize-based services, OntimizeWeb allows integration with third-party APIs using the **JSON:API** specification. This allows standardized communication with external systems and services. + +## Overview + +To use [**JSON:API**](https://jsonapi.org/){:target="\_blank"}, OntimizeWeb provides an `BaseDataService`, an abstract class that allows developers to implement full CRUD operations aligned with JSON:API conventions. + +OntimizeWeb is compatible with servers that implement the **JSON:API specification** for standardized data exchange. By default, OntimizeWeb doesnot use the JSONAPIService to perform CRUD operations according to this standard. If needed, you can also configure the application to use services that extend `JSONAPIService` by setting the `serviceType` attribute in the [application configuration]({{ base_path }}/guide/appconfig/#application-configuration-file){:target="_blank"} or in the component's `service-type` input or provides this service using the `O_DATA_SERVICE` injection token in your application module. + +### JSON:API services methods + +Service `JSONAPIService` has the same methods for configuring and sending request to the server. This methods are the following: + +```javascript +/* Configuration methods */ +getDefaultServiceConfiguration(serviceName?: string): Object; +configureService(config: any): void; +buildHeaders():void; + +/* CRUD methods */ +queryById(queryParams: JSONAPIQueryParameter): Observable ; +query(queryParams: JSONAPIQueryParameter): Observable; + +insert(attributes: object, type: string): Observable; +update(id: string | object, attributes: object, type: string): Observable; +delete(id: object): Observable; + + +/** +* Successful response parsers, there is one parser for each CRUD method which calls to the common parser. +* User can overwrite the chosen methods parsers or the common parser +*/ +protected parseSuccessfulResponse(resp: JSONAPIResponse, _innerObserver: Subscriber); +protected parseSuccessfulQueryResponse(resp: JSONAPIResponse, _innerObserver: Subscriber); +protected parseSuccessfulAdvancedQueryResponse(resp: JSONAPIResponse, _innerObserver: Subscriber); +protected parseSuccessfulInsertResponse(resp: JSONAPIResponse, _innerObserver: Subscriber); +protected parseSuccessfulUpdateResponse(resp: JSONAPIResponse, _innerObserver: Subscriber); +protected parseSuccessfulDeleteResponse(resp: JSONAPIResponse, _innerObserver: Subscriber); + +/** +* Unsuccessful response parsers, there is one parser for each CRUD method which calls to the common parser. +* User can overwrite the chosen methods parsers or the common parser +*/ + +protected parseUnsuccessfulResponse(error: HttpErrorResponse, _innerObserver: Subscriber); +protected parseUnsuccessfulQueryResponse(error: HttpErrorResponse, _innerObserver: Subscriber); +protected parseUnsuccessfulAdvancedQueryResponse(error: HttpErrorResponse, _innerObserver: Subscriber); +protected parseUnsuccessfulInsertResponse(error: HttpErrorResponse, _innerObserver: Subscriber); +protected parseUnsuccessfulUpdateResponse(error: HttpErrorResponse, _innerObserver: Subscriber); +protected parseUnsuccessfulDeleteResponse(error: HttpErrorResponse, _innerObserver: Subscriber); + +/* Authentication methods */ +startsession(user: string, password: string): Observable +endsession(user: string, sessionId: number): Observable; +hassession(user: string, sessionId: any): Observable; +``` + +### CRUD methods + +The *CRUD* (Create, Read, Update and Delete) methods are used to perform standard [**JSON:API**](https://jsonapi.org/){:target="\_blank"} operations: + +#### Common Query Parameter + +All data retrieval methods use a shared parameter type called **JSONAPIQueryParameter**, which allows filtering, sorting, pagination, and other options when querying resources. + +- **`JSONAPIQueryParameter`**: Object used to define filtering and query parameters when requesting resources. + If the object is empty, no filters or query options will be applied. + + - **`id`**: Unique identifier of the resource. + - **`type`**: Resource type (e.g., `"articles"`, `"users"`). + - **`attributes`**: Object containing resource-specific data fields. + - **`relationships`**: Object that defines relationships between the resource and other JSON:API resources. + - **`links`**: Object containing hyperlinks related to the resource. + - **`meta`**: Object for non-standard meta-information that cannot be expressed as attributes or relationships. + - **`page`**: Object used for pagination parameters (e.g., `number`, `size`). + - **`include`**: Comma-separated list of related resources to include by default. + - **`fields`**: Sparse fieldsets. Limits the attributes and relationships returned per resource type. + - **`filter`**: Object used to apply filtering conditions to the request. + > **Note**: JSON:API is agnostic about filtering strategies; server-specific implementations may vary. + - **`sort`**: Comma-separated list of fields used to sort the results. Use `-` prefix for descending order (e.g., `-created,title`). + +#### Method Definitions +- **query**: performs a request to get data from the server. + - **JSONAPIQueryParameter** + +- **advancedQuery**: performs a request to get **paginated** data from the server. + - **JSONAPIQueryParameter** + +- **insert**: performs a insert operation request to the server. + - **attributes**: indicates the values to insert. + - **type**: indicates the type to perform the request. + +- **update**: performs an update operation request to the server. + - **ids**: indicates the keys values for performing the update. + - **attributes**: indicates the values to update. + - **type**: indicates the type to perform the request. + +- **delete**: performs an delete operation request to the server. + - **ids**: indicates the keys values for performing the deletion. + - **type**: Resource type. + + +### Server response interface + +The standard response from requests made to JSON:API-based servers always follows this structure: + +```javascript +import { BaseResponse } from './base-response.interface'; +// Interface for describing errors +interface JSONAPIError { + id?: string; // Unique identifier for this particular error occurrence + status?: string; // HTTP status code applicable to this problem + code?: string; // Application-specific error code + title?: string; // Short, human-readable summary of the problem + detail?: string; // Detailed explanation of the error + source?: { + pointer?: string; // JSON Pointer to the offending part of the document + parameter?: string; + header?: string // a string indicating the name of a single request header which caused the error + }; + links?: { + about?: string; // A link that leads to further details about this error + type?: string; // Optional additional links + }; + meta?: Record; // Optional additional information +} + +type JsonApiLinkValue = + | string // Simple URI string + | JsonApiLinkObject // Full link object with metadata + | null; + +// Interface for links (can be extended as needed) +interface JSONAPILinks { + + [linkName: string]: JsonApiLinkValue; // Dynamic keys: "self", "related", etc. +} + +interface JsonApiLinkObject { + href: string; // Required: The actual link URI + meta?: Record; // Optional metadata about the link + rel?: string; // Optional: Relation type (if not inferred) + type?: string; // Optional: Media type of the resource + title?: string; // Optional: Human-readable title +} + +// Interface for resources +interface JSONAPIResource { + type: string; // Resource type (e.g., "articles", "users") + id: string; // Unique identifier of the resource + attributes?: Record; // Attributes of the resource + relationships?: Record; // Relationships with other resources (optional) + links?: JSONAPILinks; // Links related to the resource (optional) + meta?: Record; // Metadata (optional) +} + +// Interface for successful responses +interface JSONAPISuccessfulResponse { + data?: JSONAPIResource | JSONAPIResource[]; // Can be a single resource or a collection + included?: JSONAPIResource[]; // Related resources (optional) + meta?: Record; // Metadata (optional) + links?: JSONAPILinks; // Links (optional) +} + +// Interface for error responses +interface JSONAPIErrorResponse { + errors?: JSONAPIError[]; // A list of errors +} + +// Generic interface that can be used for any API response, either successful or error +export interface JSONAPIResponse extends JSONAPISuccessfulResponse, JSONAPIErrorResponse, BaseResponse { }; + + +``` + +You can see an example of a JSON:API service request/response in the images below. You can see the complete response [here]({{ base_path }}/assets/examples/jsonapi_service_request_example_response.json){:target='\_blank'}. + +![JSON:API service request example]({{ base_path }}/assets/images/jsonapi-request.png){: .align-center} + +![JSON:API service response example]({{ base_path }}/assets/images/jsonapi-response.png){: .align-center} + +### Request arguments interface + +In **OntimizeWeb**, services like **JSONAPIService** are responsible for constructing the request sent to the backend. To allow flexibility, the framework provides a **mechanism to intercept and transform request parameters** before they are serialized and sent — this is done using a service adapter. + +You can define a custom adapter by implementing the following interface: + +``` +export interface IBaseRequestArgument { + parseQueryParameters(params: any): any; +} +``` + + +### Use JSONAPIService in your application + +Check the example below about how to configure and use the `JSONAPIService` for querying data in your application. + +```javascript +protected service: JSONAPIService; + +constructor(protected injector: Injector) { + this.service = this.injector.get(JSONAPIService); +} + +ngOnInit() { + this.configureService(); +} + +protected configureService() { + // Configure the service using the configuration defined in the `app.services.config.ts` file + const conf = this.service.getDefaultServiceConfiguration('movements'); + this.service.configureService(conf); +} + +getMovements(data) { + if (data.hasOwnProperty('ACCOUNTID') && this.service !== null) { + const filter = { + 'ACCOUNTID': data['ACCOUNTID'] + }; + const columns = [this.yAxis, this.xAxis, 'DATE_']; + + //Note: JSON:API is agnostic about filtering strategies; server-specific implementations may vary. + this.service.query({fields: {movement:columns}, filter:filter}).subscribe(resp => { + if (resp.isSuccessful() === 0) { + + // resp.data contains the data retrieved from the server + + } else { + alert('Impossible to query data!'); + } + }); + } +``` + +### Create and extend a service + +> ⚠️ **Note:** Rick and Morty API does not support **JSON:API** specification + +Create a new service class that extends to `JSONAPIService` in **OntimizeWeb**. In the following example we are creating a service called `RickAndMortyService` that extends the class `JSONAPIService` + +```javascript +import { Injectable, Injector } from '@angular/core'; + +import { OntimizeBaseService } from 'ontimize-web-ngx'; + +@Injectable() + export class RickAndMortyService extends JSONAPIService { + + + constructor(protected injector: Injector) { + super(injector); + //Uses Request Arguments to Adapter to prepare params + this.requestArgumentAdapter = this.injector.get(RickAndMortyRequestArgumentsAdapter); + } + + public configureService(config: any): void { + super.configureService(config); + this.path = config.path; + } + + public configureAdapter() { + //Converts API responses to Ontimize format + this.adapter = this.injector.get(RickAndMortyResponseAdapter); + } + + } +``` + +Once your service is created you can [override the JSON:API CRUD methods](#override-crud-methods-using-a-third-party-api) and/or [define new methods](#define-your-own-crud-methods). After that you must decide if the service will be used [in the whole application](#use-your-service-in-the-whole-application) or only in [specific components](#use-your-service-in-a-specific-component). + +### Override CRUD methods using a third party API + +You can use your service to retrieve or send data to a third party API. The following example shows the service from the previous step consuming the [Rick and Morty API](https://rickandmortyapi.com/){:target="\_blank"} for querying different entities. We have overridden the `query` and `advancedQuery` methods for making simple and paginated request to the API. Note that you must [adapt the API response](#adapt-your-service-response) to the ontimize service response for using the retrieved data with the **OntimizeWeb** components. + +```javascript +import { Observable } from 'rxjs'; + +import { Injectable, Injector } from '@angular/core'; +import { JSONAPIQueryParameter, JSONAPIService, ServiceResponse, Util } from 'ontimize-web-ngx'; +import { RickAndMortyResponseAdapter } from './rickandmorty-response-adapter'; +import { RickAndMortyRequestArgumentsAdapter } from './rickandmorty-request-adapter'; + + +@Injectable() +export class RickAndMortyService extends JSONAPIService { + constructor(protected injector: Injector) { + super(injector); + this.requestArgumentAdapter = this.injector.get(RickAndMortyRequestArgumentsAdapter); + } + + public configureService(config: any): void { + super.configureService(config); + this.path = config.path; + } + + public configureAdapter() { + this.adapter = this.injector.get(RickAndMortyResponseAdapter); + } + + query(queryParams: JSONAPIQueryParameter): Observable < ServiceResponse > { + const offset: number = (Util.isDefined(queryParams.page['offset'])) ? queryParams.page['offset'] : 0; + + // Calculate page + let page = 0; + if(Util.isDefined(offset)) { + page = Math.trunc(offset / queryParams.page['limit']) + 1; + } + + const queryParamsToString = this.toQueryParams(queryParams.filter); + const queryParamsString = ((Util.isDefined(queryParams.filter) && !Util.isObjectEmpty(queryParams.filter)) ? (queryParamsToString + '&') : '?') + 'page=' + page + + let url = `${this.urlBase}${this.path}${queryParamsString}`; + + return this.doRequest({ + method: 'GET', + url: url, + options: {} // This overrides the default http headers. Remove it if you are using an ontimize based API in the backend + }); + } + + queryById(args_0: any, ...args: any[]): Observable { + let url = `${this.urlBase}${this.path}`; + + return this.doRequest({ + method: 'GET', + url: url, + options: {} // This overrides the default http headers. Remove it if you are using an ontimize based API in the backend + }); + } + + + insert(args_0: any, ...args: any[]): Observable { + throw new Error('Method not implemented.'); + } + + update(args_0: any, ...args: any[]): Observable { + throw new Error('Method not implemented.'); + } + + delete(args_0: any, ...args: any[]): Observable { + throw new Error('Method not implemented.'); + } + + + + /** + * Converts a filter object into a query parameter string for a REST request, + * adapted to the Rick and Morty API. + * + * This method removes wildcard characters like `%` (e.g., from SQL-like search patterns), + * and properly encodes keys and values for safe use in a URL. + * + * It also filters out null, undefined, or empty values. + * + * @param obj An object with key-value pairs representing the search filters (e.g., { name: '%rick%' }) + * @returns A query string formatted for use in a URL (e.g., "?name=rick") + * + * @example + * toQueryParams({ name: '%morty%', gender: '%male%' }); + * // Returns: "?name=morty&gender=male" + */ + public toQueryParams(obj: Record): string { + const params = Object.entries(obj) + .filter(([_, value]) => !!value) // remove null/undefined/empty values + .map(([key, value]) => { + const cleanValue = value.replace(/%/g, ''); // remove wildcard % + return `${encodeURIComponent(key)}=${encodeURIComponent(cleanValue)}`; + }) + .join('&'); + return `?${params}`; + } +} + +```