Defining Intelligent Business Objects

Intelligent business objects are described in the Intelligent Business Objects section.

In order to define an intelligent business object the configurator has to click on the “Communication” property of a business object and define communication channels of the object in the “Communication Channels” dialog that comes up.

AwareIM supports the following types of communication channels out-of-the-box:

1. E-mail channel – //communication with an intelligent business object is via e-mail - //SOAP channel – communication with an intelligent business object is via Web services mechanism which supports SOAP (Simple Object Access Protocol)
2. URL channel – communication with an intelligent business object is via HTTP URL (Unified Resource Locator)
3. REST channel – communication with an intelligent business object is via a popular REST protocol

In addition to the above pre-defined types it is possible to plug-in custom channel types – see “AwareIM Programmer’s Reference”.

A particular object may expose several communication channels at once – when a notification or service request are sent to the object it is possible to indicate which type of channel the request or notification should be sent through (see SEND and REQUEST SERVICE actions). Therefore the configurator has to indicate which channels the intelligent business object exposes.

Every channel has certain properties specific to its type. To set the properties of a channel tick the channel type in the “Communication Channels” dialog and define its properties.

When an e-mail channel is defined for a business object the Configuration Tool automatically adds the EmailAddress attribute to the business object. This attribute can be used to set the e-mail address of a particular instance of the business object in the Operation Mode. When the e-mail channel is removed from the business object the EmailAddress attribute is automatically removed as well.

To specify account settings for sending emails double-click on the business space version and select the Outgoing Emails property - see Sending Outgoing E-mails.

Before setting properties of the SOAP channel, check out documentation of the service provider to find out the location of a WSDL file. This file describes how to call the SOAP services exposed by the service provider. You need to enter the URL of this WSDL file into the SOAP Channel dialog. If location of this file is different at runtime, enter the Runtime URL of the WSDL file.

The next step is to discover web services offered through this channel. AwareIM will read information in the WSDL file to automatically figure out which services are exposed by the intelligent object.

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>

<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>

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 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 www.provider.com the service requests will be sent to the following address:

www.provider.com?Parameter1=value1&Parameter2=value2&Parameter3=value3

where value1, value2 and value3 are values of the Parameter1, Parameter2 and Parameter3 attributes respectively.

The following properties should be specified:

This is the URL where the requests will be sent. This property is mandatory.

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:

www.provider.com?Parameter1=value1&Parameter2=value2&Parameter3=value3&successURL=returnURL

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.

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).

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.

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.

The optional description of the service: what it does, how it is used etc.

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 to use when the service is called – usually GET or POST

Parameters of the service can be specified in different ways depending on what the provider requires.

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.

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:

1. Provide the text string containing all parameters (you can use tag expressions inside the string )
2. Refer to an attribute of some object in Context.
3. 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

Object.Attribute = "Value1#Value2#Value3" 

</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

Object.Attribute = "Key1~Value1|Key2~Value2|Key3~Value3" 

</callout>

To add a part, click on the “Add” button above the list of the defined parts.

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:

<<MyObject.MyAttribute>> 

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:

1. 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
2. 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.

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:

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.

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

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

<<SystemSettings.APISecret>> 

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

Some vendors require that you specify the “scope” of the service request. This is vendor-specifc – refer to the documentation of the vendor.

This value is only for OAuth 1.0. Refer to the documentation of the vendor as to which signature type you need to provide

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.

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,

<<LoggedInRegularUser.AccessToken>> 

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.

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.

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.