Send a request to an external web service and handle its result on a page

Level: intermediate

Example

Call the coindesk.com external web service from the record page of the Http Client Service custom section. Display the current BTC to the USD exchange rate.

1. Set up the page UI

1. Create a custom Http Client Service app based on the Records & business processes template. To do this, follow the guide in the user documentation: Create a custom app.

2. Open the Http Client Service form page page in the working area of the Http Client Service app page.

3. Delete the Name field the Http Client Service form page page includes by default.

4. Add a label of the BTC to the USD exchange rate.

   1. Add a Label type component to the working area of the Freedom UI Designer.

   2. Click in the action panel of the Freedom UI Designer and fill out the label properties in the setup area.

      • Set Title to "BTC to USD exchange rate."
      • Select "Caption" in the Style property.
      • Select gray in the Text color property.

      

5. Add a label that contains the value of the BTC to the USD exchange rate.

   1. Add a Label type component to the working area of the Freedom UI Designer.

   2. Click in the action panel of the Freedom UI Designer and fill out the label properties in the setup area.

      • Set Title to "BTC to USD exchange rate (value)."
      • Select "Body text" in the Style property.

      

6. Click in the action panel of the Freedom UI Designer. After you save the page settings, Creatio opens the source code of the Freedom UI page.

2. Send the web service request and handle its results

Configure the business logic in the Client Module Designer. For this example, send the web service request and handle its results.

1. Enable the sdk.HttpClientService service that sends HTTP requests. To do this, add @creatio-devkit/common to the AMD module as a dependency.

   AMD module dependencies

   /* Declare the AMD module. */
   define("UsrAppHttpClientServ_FormPage", /**SCHEMA_DEPS*/["@creatio-devkit/common"] /**SCHEMA_DEPS*/, function/**SCHEMA_ARGS*/(sdk)/**SCHEMA_ARGS*/ {
           ...
       };
   });

2. Add the BtcToUsd attribute that stores data of the bitcoin to dollar exchange rate to the viewModelConfigDiff schema section.

   viewModelConfigDiff schema section

   viewModelConfigDiff: /**SCHEMA_VIEW_MODEL_CONFIG*/{
       "attributes": {
           ...,
           /* The attribute that stores the bitcoin to dollar exchange rate. */
           "BtcToUsd": {}
       }
   }/**SCHEMA_VIEW_MODEL_CONFIG*/,

3. Bind the caption property of the BtcToUsdExchangeRateValue element to the $BtcToUsd model attribute in the viewConfigDiff schema section. The caption property handles the text contained in the element.

   viewConfigDiff schema section

   viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
       ...,
       {
           "operation": "insert",
           "name": "BtcToUsdExchangeRateValue",
           "values": {
               ...,
               /* Bind the BtcToUsd attribute to the caption property. */
               "caption": "$BtcToUsd",
               ...
           },
           ...
       }
   ]/**SCHEMA_VIEW_CONFIG_DIFF*/,

4. Add a custom implementation of the crt.HandlerViewModelInitRequest system query handler to the handlers schema section. Execute the handler when Creatio initializes the View model.

   1. Create an instance of the HTTP client from @creatio-devkit/common.
   2. Specify the URL to retrieve the current rate. Use the coindesk.com external web service.
   3. Send a GET request.
   4. Retrieve the rate from the response and specify the rate in the BtcToUsd attribute.
   handlers schema section

   handlers: /**SCHEMA_HANDLERS*/[
       {
           request: "crt.HandlerViewModelInitRequest",
           /* The custom implementation of the system query handler. */
           handler: async (request, next) => {
               /* Create an instance of the HTTP client from @creatio-devkit/common. */
               const httpClientService = new sdk.HttpClientService();
               /* Specify the URL to retrieve the current rate. Use the coindesk.com external service. */
               const endpoint = "https://api.coindesk.com/v1/bpi/currentprice/USD.json";
               /* Send a GET request. The HTTP client converts the response body from JSON to a JS object automatically. */
               const response = await httpClientService.get(endpoint);
               /* Retrieve the rate from the response and specify the rate in the BtcToUsd attribute. */
               request.$context.BtcToUsd = response.body.bpi.USD.rate;
               /* Call the next handler if it exists and return its result. */
               return next?.handle(request);
           },
       },
   ] /**SCHEMA_HANDLERS*/,

5. Click Save on the Client Module Designer's toolbar.

Outcome of the example

To view the outcome of the example:

1. Open the Http Client Service app page and click Run app.
2. Click New on the Http Client Service app toolbar.

As a result, Creatio will display the current BTC to the USD exchange rate on the record page of the Http Client Service custom section. The value will be retrieved from the coindesk.com external web service.

Source codes

UsrAppHttpClientServ_FormPage

/* Declare the AMD module. */
define("UsrAppHttpClientServ_FormPage", /**SCHEMA_DEPS*/["@creatio-devkit/common"] /**SCHEMA_DEPS*/, function/**SCHEMA_ARGS*/(sdk)/**SCHEMA_ARGS*/ {
    return {
        viewConfigDiff: /**SCHEMA_VIEW_CONFIG_DIFF*/[
            {
                "operation": "insert",
                "name": "BtcToUsdExchangeRate",
                "values": {
                    "layoutConfig": {
                        "column": 1,
                        "row": 1,
                        "colSpan": 1,
                        "rowSpan": 1
                    },
                    "type": "crt.Label",
                    "caption": "#ResourceString(BtcToUsdExchangeRate_caption)#",
                    "labelType": "caption",
                    "labelThickness": "normal",
                    "labelEllipsis": false,
                    "labelColor": "#757575",
                    "labelBackgroundColor": "transparent",
                    "labelTextAlign": "start"
                },
                "parentName": "LeftAreaProfileContainer",
                "propertyName": "items",
                "index": 0
            },
            {
                "operation": "insert",
                "name": "BtcToUsdExchangeRateValue",
                "values": {
                    "layoutConfig": {
                        "column": 1,
                        "row": 2,
                        "colSpan": 1,
                        "rowSpan": 1
                    },
                    "type": "crt.Label",
                    /* Bind the BtcToUsd attribute to the caption property. */
                    "caption": "$BtcToUsd",
                    "labelType": "body-1",
                    "labelThickness": "normal",
                    "labelEllipsis": false,
                    "labelColor": "#181818",
                    "labelBackgroundColor": "transparent",
                    "labelTextAlign": "start"
                },
                "parentName": "LeftAreaProfileContainer",
                "propertyName": "items",
                "index": 1
            }
        ]/**SCHEMA_VIEW_CONFIG_DIFF*/,
        viewModelConfigDiff: /**SCHEMA_VIEW_MODEL_CONFIG*/{
            "attributes": {
                "Id": {
                    "modelConfigDiff": {
                        "path": "PDS.Id"
                    }
                },
                /* The attribute that stores the bitcoin to dollar exchange rate. */
                "BtcToUsd": {}
            }
        }/**SCHEMA_VIEW_MODEL_CONFIG*/,
        modelConfigDiff: /**SCHEMA_MODEL_CONFIG*/{
            "dataSources": {
                "PDS": {
                    "type": "crt.EntityDataSource",
                    "config": {
                        "entitySchemaName": "UsrAppHttpClientServ"
                    }
                }
            }
        }/**SCHEMA_MODEL_CONFIG*/,
        handlers: /**SCHEMA_HANDLERS*/[
            {
                request: "crt.HandlerViewModelInitRequest",
                /* The custom implementation of the system query handler. */
                handler: async (request, next) => {
                    /* Create an instance of the HTTP client from @creatio-devkit/common. */
                    const httpClientService = new sdk.HttpClientService();
                    /* Specify the URL to retrieve the current rate. Use the coindesk.com external service. */
                    const endpoint = "https://api.coindesk.com/v1/bpi/currentprice/USD.json";
                    /* Send a GET request. The HTTP client converts the response body from JSON to a JS object automatically. */
                    const response = await httpClientService.get(endpoint);
                    /* Retrieve the rate from the response and specify the rate in the BtcToUsd attribute. */
                    request.$context.BtcToUsd = response.body.bpi.USD.rate;
                    /* Call the next handler if it exists and return its result. */
                    return next?.handle(request);
                },
            },
        ] /**SCHEMA_HANDLERS*/,
        converters: /**SCHEMA_CONVERTERS*/{}/**SCHEMA_CONVERTERS*/,
        validators: /**SCHEMA_VALIDATORS*/{}/**SCHEMA_VALIDATORS*/
    };
});

---

Resources

Package with example implementation