1. REST API Guide
  2. Overview of the REST Outbound Proxy Business Service

Overview of the REST Outbound Proxy Business Service

The following figure shows the Business Services pane with the business service: SwaggerPetstoreUPOpenAPI30. It also shows the Business Service Methods pane, and the method name: addPet:post.

The surrounding text describes the Business Services pane.

Business Services

The first object generated by the WSDL/JSON Import Wizard is a REST outbound proxy business service belonging to the CSSWSRESTOutboundDispatcher class. This service acts as a client-side implementation of the REST API endpoint, and it includes the business methods and arguments that correspond to the operations, or OperationId fields, defined in the imported JSON document.

The business service name is derived from the title value in the JSON document. In this example, the business service is called: SwaggerPetstoreUPOpenAPI30. The names of the generated repository artefacts derive from the imported OpenAPI JSON file. A number is appended to each business service, business service method, business method arguments, integration objects and integration components depending on how often you have imported a specific JSON file into Web Tools.

If the names can't be formatted into a standard Siebel naming standard, for example, if the name is too long or if it contains special characters, then the WSDL/JSON Import Wizard automatically generates these names. The original names are available in the Comments field, under the Business Service.

Business Methods

Each operation or OperationId value listed in the JSON file becomes a business service method under the generated REST outbound proxy business service. Business methods are named as follows:

  • The verb under the path is appended to the OperationId value. In our sample JSON file, the OperationId is AddPet and post is the verb of the path. The business service method is called: addPet:post

  • If the JSON file has no OperationId values, then the JSON file import removes all special characters from the path name and combines it with the required verb to create the business method name.

  • If the path name is longer than the Siebel standard length, then the business method is named as follows: Mth<serial number><business service>:<verb> For example: Mth10SwaggerPetstoreUPOpenAPI30:get
    Note: The serial number is between 1 and 999. It starts at 1, and is incremented by 1 for every method created.

Business Arguments

The JSON Import Wizard generates method arguments in addition to the proxy business service in the repository. In 3.0 JSON Specification, Request is moved out of the parameters and provided under requestBody in the JSON file . The parameters listed under the path node in the JSON file become proxy business method arguments. The method argument name derives from the name property only for the parameter. For requestBody and responses in the JSON file, there are no names provided in the JSON specification. For requestBody the name is body:body and for Responses the name has prefix Res to response code and suffixed with :res. For example the name for response code 200 would be like Res200:res. When you provide the input values for business service method arguments, you can provide these in any order. JSON does not require inputs to be in a specific order.

The following figure shows a file with 3.0 JSON specification:

This figure shows a file with 3.0 JSON specification.

Parameters listed in JSON files can be any of the following:

  • Simple parameters. Integers, strings, boolean, and decimal number become simple method arguments with corresponding Siebel types.
  • Complex parameters.
    • Complex parameters can be with $ref references to definitions under components or without references in the JSON file having type as object or array, and can become integration objects.
    • If there are simple or complex parameters as arrays, or complex parameters without a $ref reference, then these parameters also become integration objects.
    • They are named by appending the new business service to the automatically generated integration object name.
    • Complex parameters can be derived from JSON file under parameters, requestBody, or responses in the JSON file.
    • If the complex parameters are derived from JSON file under parameters, then the naming convention for the integration objects would be like Arg<serial number><business service>:<in>

      For example: Arg4SwaggerPetstoreUPOpenAPI30:query

      In this example, the <in> value specifies where this parameter is defined in the outbound call, such as query, header, path, formData and cookie.

    • If the complex parameters is derived from JSON file under requestBody, then the naming convention for the integration objects would be like Req<serial number><business service>:body

      For example Req2SwaggerPetstoreUPOpenAPI30:body

    • If the complex parameters are derived from JSON file under responses, then the naming convention for the integration objects would be like Res<serial number><business service>:res

      For example Res2SwaggerPetstoreUPOpenAPI30:res

    The following suffixes are used with business service method arguments:

    • :path. This argument substitutes the path parameter for the appropriate value.

      For example, in the following URI:

      /store/order/{orderId}

      In the business service method argument, the parameter orderId becomes orderId:path. The value which the user provides at runtime replaces this path parameter. For example, if you provide the value 123456 for orderId:path, then at runtime this is substituted for /store/order/123456.
    • :query. This argument is passed as a query parameter in the URL.
    • :header. This argument is passed as an header parameter in the request.
    • :security. This argument is used as a security parameter where required in the request.
    • :body. This argument is used as the request body.
    • :res. This argument is used to map the response received from the host server.
  • Security parameters. These parameters are appended with the suffix security, for example: username:security. As of this release, there are two security parameters retained from earlier 20.8 release. They are username:security and password:security. These two parameters are retained for backward compatibility with 20.8 release. These two parameters can aid in basic authentication only. For other security schemes/authentication requirement, use the Filter service. For more information, see Overview of the REST Outbound Filter Service.
Note: From Siebel CRM 20.8 Update release, only basic authentication was supported, so you could only pass the username:security and password:security arguments at runtime. From Siebel CRM 22.9 Update release, other authentication mechanisms are supported by way of Filter Service and Filter methods using Request and Response Filter in the Application Administration > Web Services > Outbound REST Services UI.
Note: Outgoing REST requests using Basic Authentication must contain the following three parameters to avoid an error from an external system which may be a variation of "authorization needed".
Parameter Name Value
type:security Basic
username:security The user name for the external system
password:security The user’s password

The following figure shows the Business Service Method Arguments pane. This pane lists the method argument generated from a complex parameter: Arg1SwaggerPetstoreUPOpenAPI30. It also lists the method arguments security parameters username:security and password:security for backward compatibility with 20.8 upgrade for basic authentication usage.

The surrounding text describes the methods and arguments of the business service.

In the above figure, the method name is generated from operationId if provided in the JSON file like <operationId>:<operation>. For example, in the above figure, the name findPetsByTags is the operationId and get is the operation verb, therefore the method name generated is findPetsByTags:get after preprocessing the operationId string for any special characters and reducing the length within 75 chars. If these conditions are not satisfied, then a method name like Mth<serial number><business service>:<verb> is generated. For example: Mth10SwaggerPetstoreUPOpenAPI30:get.

In the above example, for business service method argument, name is taken from the name property under parameters which is tags and the in property which is query. Hence the Business Service Method Argument name is generated as tags:query. As the parameter is of type array, an Integration Object is generated to represent the data for this parameter at runtime. The Integration Object name is generated like Arg<serial number><business service>:<in> which then becomes Arg1SwaggerPetstoreUPOpenAPI30:query in the above example. The optional column is checked for argument Arg1SwaggerPetstoreUPOpenAPI30:query, as the JSON file specifies required value as false. So, at runtime, when invoking this proxy Business Service, providing this argument is optional.

Note: If the JSON file does not specify the data types clearly, then it would be defaulted to String / DTYPE_TEXT while creating the Business Service Arguments / Integration Fields. For number data type in JSON file, if format is not specified, then it will be defaulted to double. For integer data type in JSON file, if the format is not specified then it will be defaulted to integer (int32).