Differences

This shows you the differences between two versions of the page.

--- 2500_config_apps:0500_add_edit_objects:0600_intelligent_bo [2026/08/13 03:33] – localdev
+++ 2500_config_apps:0500_add_edit_objects:0600_intelligent_bo [2026/08/13 03:38] (current) – localdev
@@ Line 1: / Line 1: @@
-{{tag>Config Intelligent_Business_Object Email Outgoing SOAP}}
+{{tag>Config Intelligent_Business_Object Email Outgoing SOAP URL REST Index}}
 [<10>]
 ====== Defining Intelligent Business Objects ======
@@ Line 36: / Line 36: @@
 <callout type="primary" icon="true" title="note"> If the service provider changes definitions of services the services may be re-discovered in the same way as described above. The Configuration Tool will automatically replace all services and business objects declared as service input and replies with the new definitions.</callout>
+===== Setting Properties of the URL Channel =====
+Communication with an intelligent business object via the URL channel assumes that //**AwareIM**// sends service requests to the specified URL. It is expected that when this URL is called the browser will go to the web site of the service provider. When this web site finishes its task it will return to the //**AwareIM**//-based application, A typical scenario for the URL channel service is a payment system (such as PayPal) that collects credit card details and returns to the web site of the merchant.
+If services exposed by the business object require input (see [[2500_config_apps:2000_add_edit_services|Defining Services]]) the attribute values of the business object instances representing service input will be passed to the specified URL as request parameters. For example, if a service requires the business object URLParameters that has ''Parameter1'', ''Parameter2'' and ''Parameter3'' attributes defined and the provider’s URL is [[http://www.provider.com/|www.provider.com]] the service requests will be sent to the following address:
+<code>www.provider.com?Parameter1=value1&Parameter2=value2&Parameter3=value3</code>
+where ''value1'', ''value2'' and ''value3'' are values of the ''Parameter1'', ''Parameter2'' and ''Parameter3'' attributes respectively.
+The following properties should be specified:
+==== URL of the service provider ====
+This is the URL where the requests will be sent. This property is mandatory.
+==== Request parameter identifying the URL to return to if success ====
+The service provider represented by the intelligent business object may expect that the request contain the URL that the provider should return to in case of the successful fulfilment of the service. //**AwareIM**// will take care of supplying the appropriate URL provided that it knows the name of the request parameter that should contain this URL. For example, if you specify ''successURL'' as a request parameter the service request sent to the service provider will be:
+<code>www.provider.com?Parameter1=value1&Parameter2=value2&Parameter3=value3&successURL=returnURL</code>
+where ''returnURL'' is the value that //**AwareIM**// will supply so that when the reply from the provider is delivered via this URL //**AwareIM**// will know that the service has been completed successfully. If this parameter is not specified //**AwareIM**// will assume that any service request sent to the provider has been successfully completed without waiting for any reply from the provider.
+==== Request parameter identifying the URL to return to if a failure occurs ====
+This is the same as the previous parameter except that the return URL indicates failure rather than success. If this parameter is not specified //**AwareIM**// will either assume that any service request sent to the provider has been successfully completed without waiting for any reply from the provider (if success request parameter is also not specified) or it will wait for the service reply from the provider and if the provider’s service fails the service request will eventually time out (this scenario should be avoided unless the provider’s service can never fail).
+===== Setting Properties of the REST Channel =====
+Communication through the REST channel involves sending an HTTP call to a particular URL. Unlike the URL channel no user interface is involved in the call – the service returns straight away and the execution of the rules continues. Services exposed by an intelligent object through the REST channel can be discovered if the provider supplies a file in an Open API format describing exposed services. They can also be added manually as described below.
+To discover services automatically click on the “Discover” button above the services table. Then provide the URL of the file in the Open API format (with .json or .yaml extension). AwareIM will automatically discover services exposed by the provider and will display them. You can then select the services you will be using in your application.
+To add a service manually, click on the “Add” button above the services table. To edit the service details click on the “Edit” button and to delete a service click on the Delete button. You can also copy a service that you have already defined to use it as a basis for another service. To do this select a service, click on the “Copy” button, then click on the “Paste” button to create a duplicate of the service and then click on the “Edit” button to modify it.
+The following properties can be specified when adding/editing a service.
+==== Name ====
+Specify the name of the service. The name must be unique among other services of the business object. The name must start with a character or underscore symbol and contain characters, digits or underscore symbols. Spaces are not allowed in the name.
+==== Description ====
+The optional description of the service: what it does, how it is used etc.
+==== Base URL ====
+The URL to call when the service is requested. This URL should not include any URL parameters. You can use tag expressions to refer to attributes of the objects in Context here.
+==== HTTP Verb ====
+HTTP verb to use when the service is called – usually ''GET'' or ''POST''
+==== Parameters ====
+Parameters of the service can be specified in different ways depending on what the provider requires.
+==== URL-encoded string ====
+If a provider requires that parameters must be specified in the URL of the call, specify them here. You can use tag expressions to refer to attributes of the objects in Context.
+==== Request Body ====
+Use these values if parameters need to be encoded into the body of the request. You can define further details if you click on the Details link to bring up the Request Body dialog.
+A body of the request may consist of several “parts” if parameters include binary content. Usually, though, the request contains just one part. To specify the content of the part you can do either the following:
+  - Provide the text string containing all parameters (you can use tag expressions inside the string )
+  - Refer to an attribute of some object in Context.
+  - Refer to the entire object in Context.
+To specify parameters as a string you should select “text/plain” as Content Type and then provide the parameter string by selecting the “Use this String” radio button. The string may refer to attributes of the objects in Context using tag expressions.
+The value of the parameter may also be stored in an attribute of some object in Context in which case you should select the “Take From Context” radio button and then select the name of the object and attribute that holds the parameter. You also need to specify the correct Content Type of the value stored in the attribute.
+If you select the “Take From Context” radio button, specify the object, but do not specify the attribute, //**AwareIM**// will automatically convert the entire instance of the object either into JSON or XML representation (depending on whether the Content Type is specified as “application/json” or “text/xml”. You can then customize how the conversion will occur by clicking on the “Name Mapping” and “Attribute Encoding” links and also specifying how undefined values will be encoded.
+If your service provider requires that you provide binary content as a parameter along with some primitive values (for example, text or number) you should specify each parameter in its own part. For example, if you need to provide a binary value and a number, you should define two parts – the first part (binary) should have “application/octet-stream” as Content Type and it should refer to the attribute of some object in Context of the Picture or Document types. The second part should have “text/plain” as Content Type and then refer to some attribute of the Number or Plain Text type.
+<callout type="primary" icon="true" title="note"> If you are referring to the entire object in Context and this object has an attribute of the Picture or Document type, the picture or document will be automatically encoded without you having to define an additional part.</callout>
+<callout type="primary" icon="true" title="note"> If a provider requires that the value of some attribute is an array of primitive values and you are referring to the entire object in Context, make sure that the value of the “array” attribute is a string that concatenates all array members delimited by the “#” symbol, for example <code aim>Object.Attribute = "Value1#Value2#Value3" </code></callout>
+<callout type="primary" icon="true" title="note"> If a provider requires that the value of some attribute is a dictionary and you are referring to the entire object in Context, make sure that the value of the “dictionary” attribute is a string containing pairs of key/values separated by the "|" symbol. Each key/value pair must be separated by the "~" symbol, for example <code aim>Object.Attribute = "Key1~Value1|Key2~Value2|Key3~Value3" </code></callout>
+To add a part, click on the “Add” button above the list of the defined parts.
+==== HTTP Headers ====
+Click on the “HTTP Headers” link to define one or more optional HTTP headers that will be added to the HTTP request if the provider requires them. For each header provide its name and value. Note that the value may refer to the current Context of the process when the service is called. To do this, enclose the value in “tags” (double angular brackets), for example: <code aim><<MyObject.MyAttribute>> </code>
+==== Reply ====
+If the REST call returns a reply that you need to handle in your application, you should select the “Reply returned of type” radio button and then click on the "Details" link to provide further details. Defining a reply is similar to to defining the body of a request (see “Parameters” above). However, when you define a reply, you should always specify just one part:
+  - For text replies all you can do is write the string with the reply into some attribute of an existing object in Context of the process where the service is called. You need to specify the name of the object and the attribute where the reply will be stored. You will then need to add further rules to analyse the provided reply and perform further actions
+  - For JSON and XML replies you can get //**AwareIM**// to automatically parse the contents of the reply into attributes of some object. //**AwareIM**// will create a new instance of such object and populate its attributes from the values of the corresponding fields in the reply. By default //**AwareIM**// will try to find an attribute with exactly the same name as in the JSON/XML attribute definition, but you can also provide your own mapping between names in JSON/XML and the corresponding //**AwareIM**// attribute names.
+==== OAuth Support ====
+Many vendors providing REST services support OAuth protocol that mandates that the caller of the service authenticates himself using a special protocol before a call to the service is made. If this is the case you need to tick the “OAuth Supported” checkbox underneath the services table and then click on the “Details” button to provide further details:
+==== Provider ====
+//**AwareIM**// already includes settings that you need to specify for many popular REST service vendors, so if your vendor is already in the list you can prepopulate most settings with vendor-specific values by selecting the vendor from the drop down list.
+You can also add your own providers to the list if you know their values. To do this modify the file ''AwareIM/ConfigTool/eclipse/plugins/com.awaresoft.awareim.configtool_xxx.jar''. This file is a zip file, so you can open it with an archiver utility. Then add the appropriate property file to the config/oauth directory within this archive, You can take a look at any existing property file in this folder for an example.
+==== OAuth version ====
+Different vendors support different versions of the OAuth protocol. The settings are quite different depending on which version is supported. Choose either version 1.0 or 2.0
+==== API Key, API Secret ====
+The caller of the service must be registered with the vendor to make OAuth-based REST calls. The vendor issues API Key and API secret to the caller. These need to be specified here. If these values are stored in the attributes of some object (for example, ''SystemSettings'') you can refer to this attribute by using tag expressions, for example <code aim><<SystemSettings.APISecret>> </code>
+Also when registering your application with a provider, make sure that you include the following URI as "redirect URI":
+[[http://YourServerName:8080/AwareIM/req.awurl|http://YourServerName:8080/AwareIM/req.awurl]]
+==== Scope ====
+Some vendors require that you specify the “scope” of the service request. This is vendor-specifc – refer to the documentation of the vendor.
+==== Signature type ====
+This value is only for OAuth 1.0. Refer to the documentation of the vendor as to which signature type you need to provide
+==== Request for request token ====
+The values in this section are only for OAuth 1.0 that requires that the system first sends a request for a "request token" to the specified URL. The URL then returns a reply that contains "request token" and "request secret". You need to specify the URL to send the request to, the HTTP verb of the request, the type of return and regular expressions to extract token and secret from the reply.
+==== Request for access token ====
+A call to the service using OAuth can only be done if the vendor issues an "access token", which is then used for authentication. To get an access token the system first needs to call an "authorization URL" that provides a special code in the reply. This code is then used in the call to the "access token URL" that returns the access token, which then needs to be stored in an attribute of some object (so that it can be used in the service call). You need to specify the “authorization URL”, the name of the parameter of the reply that contains authorization code, the “access token URL”, the regular expression that extracts access token from the reply and finally an expression where to store the access token. When specifying the expression use a tag expression, for example, <code aim><<LoggedInRegularUser.AccessToken>> </code> The object referred to in the expression must be in the Context of the service call. For more details please refer to the OAuth and vendor’s documentation.
+==== Token expiry ====
+Access tokens may expire. If a call to the service is made with an expired token an error message will be returned. The error message is specific to the vendor. If you help //**AwareIM**// identify the “token expiry” error message it will automatically invoke the access token workflow again and request a new token. Otherwise, it will just display the error message. To support automatic token expiry click on the “Token Expiry” button, tick the "Check for expired tokens" checkbox and provide the string that distinguishes token expiry error messages from other error messages.
+==== Log ====
+If you tick the Save button AwareIM will capture all communication in a log. It will record the name of the service called, time of the communication, URL parameters, HTTP method, HTTP body etc
+It will also record HTTP headers of the request and response. The log will be captured in the instance of the object that you specify (you also need to define the attributes in this object that will store the log, as well as the attribute storing the name of the service and timestamp (the latter two attributes are required, so that you can sort by time and service.
 {{simplenavi>.:0600_intelligent_bo}}

config intelligent business object email outgoing soap url rest index