Adding/Editing Services

The following section describes how to work with the editor of services when adding a new service or editing the existing one. Services are described in the Communication with Other Systems section.

The editor of services can be started as described in the Working with Configuration Elements section.

You can define the following settings of the service in the working area of the editor:

Select a process that will implement the service from a list of all processes defined in the business space version. When the service is requested the specified process will be executed. If the specified process requires input, this input must be provided by a service requestor.

Choose this option if you want Aware IM to expose the service as “web service” implementing the SOAP protocol. When the business space containing such service is published Aware IM will automatically create a WSDL file for the service.

Tick this checkbox if the service is to be exposed as REST-ful service (REST-ful service does not need any special deployment and should be available as soon as the business space is published). If you tick this checkbox you will also need to provide REST settings (see below)

Service reply defines a business object or an array of business objects sent by a service provider as a reply to the service request. If you select the “Service will return object” radio button you will need to select the object that will be returned from the list of all objects. Your implementing process must populate the context with the instance(s) of the business object being returned. Tick the “Return multiple instances” checkbox to return an array of instances. Again your implementing process must populate the context with instances of the object to be returned.

The following properties can be specified in the Element Properties window:

Specify the name of the service uniquely identifying it within the business space version. The following restrictions apply:

1. The name of the service must be unique among the names of other services defined in the business space version.
2. The name must start with a character or underscore symbol; all other symbols must be characters (including underscore symbol) or digits. Space symbols are not allowed.

Specify any text that describes what the services does etc. Providing a description is not mandatory but is highly recommended. Any description if defined is included into the generated documentation for the business space version – see Generating Documentation.

If you tick the Save button Aware IM 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.

If you ticked “Rest support” checkbox in the editor you will need to provide the following details:

Services exposed as REST will be called by other parties using a particular URL. If you choose the default option the default URL the other parties will have to use the default URL. It has the following format:

http://ServerName:port/AwareIM/REST/BusinessSpace/ServiceName?parameters

for example:

http://myserver.com:8080/AwareIM/REST/CRM/Service1?param1=value1&param2=value2

If default URL cannot be used you can construct your own URL by choosing this option and providing your own custom string. For example, if you provide the following string:

someName1/someName2

the following URL can be used:

http://ServerName:port/AwareIM/someName1/someName2?parameters

If your REST-ful service is implemented by a process that takes some object as input (should only be one object) then values of attributes of this object have to be provided as parameters in the URL (see example above). The name of the parameters must match the names of the attributes of the object. If this, however, is impossible for whatever reason, then you need to provide a mapping between the names of the parameters (“External Name”) and the name of the corresponding attribute. You should only do it for those parameters that have different names to the names of the attributes.

If a service returns a reply it can be either in the XML format (also Default) or in JSON format. The format can also vary depending on the URL used – the extension of the expected format can be specified in the URL itself. Choose the appropriate option here.

This only applies to services exposed as REST-ful services. If values of the attributes of the returned object are undefined, you can choose how Aware IM will encode such values. By default Aware IM will skip undefined values (“Do not encode” option), but you can also encode an empty value or a particular string. You can also specify different encoding options depending on the name of the attribute.