Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
2500_config_apps:0500_add_edit_objects:0600_intelligent_bo [2026/08/13 03:35] – localdev2500_config_apps:0500_add_edit_objects:0600_intelligent_bo [2026/08/13 07:20] (current) – external edit 127.0.0.1
Line 1: Line 1:
-{{tag>Config Intelligent_Business_Object Email Outgoing SOAP URL Index}}+{{tag>Config Intelligent_Business_Object Email Outgoing SOAP URL REST Index}}
 [<10>] [<10>]
 ====== Defining Intelligent Business Objects ====== ====== Defining Intelligent Business Objects ======
Line 33: Line 33:
 To discover services press the Discover button next to the Services table. Discovered services (if any) will be displayed in the Services table. You can now define a process that would call the discovered services using the REQUEST SERVICE action of the //**AwareIM**// Rule Language. To discover services press the Discover button next to the Services table. Discovered services (if any) will be displayed in the Services table. You can now define a process that would call the discovered services using the REQUEST SERVICE action of the //**AwareIM**// Rule Language.
  
-<callout type="primary" icon="true" title="note"> Business objects declared as service input and reply are automatically added to the business space version once you save the changes for the intelligent business object you are defining or editing.</callout>+<alert type="primary" icon="fa info-circle"> 
 +**note**
  
-<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>+ Business objects declared as service input and reply are automatically added to the business space version once you save the changes for the intelligent business object you are defining or editing.</alert>
  
-==== Setting Properties of the URL Channel =====+<alert type="primary" icon="fa info-circle"> 
 +**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.</alert> 
 + 
 +===== 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. 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.
Line 66: Line 72:
 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). 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 ====== +===== 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. 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.
Line 77: Line 82:
 The following properties can be specified when adding/editing a service. The following properties can be specified when adding/editing a service.
  
-===== Name =====+==== 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.  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 =====+==== Description ====
  
 The optional description of the service: what it does, how it is used etc. The optional description of the service: what it does, how it is used etc.
  
-===== Base URL =====+==== 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. 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 ====
  
 HTTP verb to use when the service is called – usually ''GET'' or ''POST'' HTTP verb to use when the service is called – usually ''GET'' or ''POST''
  
-===== Parameters =====+==== Parameters ====
  
 Parameters of the service can be specified in different ways depending on what the provider requires. Parameters of the service can be specified in different ways depending on what the provider requires.
Line 120: Line 125:
 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. 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> +<alert type="primary" icon="fa info-circle"> 
 +**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.</alert>  
 + 
 +<alert type="primary" icon="fa info-circle"> 
 +**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></alert> 
  
-<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> +<alert type="primary" icon="fa info-circle"> 
 +**note**
  
-<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> + 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></alert> 
  
 To add a part, click on the “Add” button above the list of the defined parts. To add a part, click on the “Add” button above the list of the defined parts.
  
-===== HTTP Headers =====+==== 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> 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 =====+==== 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: 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:
Line 140: Line 154:
   - 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.   - 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 =====+==== 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: 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:
Line 171: Line 185:
 This value is only for OAuth 1.0. Refer to the documentation of the vendor as to which signature type you need to provide 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 ===+==== 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. 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 ===+==== 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. 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 ===+==== 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. 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.