Page History

Open your project and go the module which contains the web service. The module now has a Schema Set. This item can be found in the bar on the left side of the screen, as can be seen below.

The Schema Set defines which entities, attributes and relations are used by the web service (they map the XSD to the domain model). This works exactly the same for REST and SOAP, and the description can be found here: Chapter 4 - Calling a SOAP service.

Using a domain schema

In version 9.2.6 we added a new element, the domain schema. This domain schema lets you define a representation of your domain that is used for the communication with a web service. In the below example, it is chosen that the status of an airport is represented by a certain set of attributes, starting with the delay. An important point to notice is that the domain schema is independent of the language that is used for the communication, and projects can add implementations of any representation not covered out of the box (JSON, XML). The domain schema that you define in studio is used as basis to create a message to a web service or to read a message from a web service. The domain schema can be translated to JSON or XML in a straightforward way, and can be inspected with the preview button.

You can see the domain schema as a sort of contract of the communication. You start with an entity that represents the begin and the end of the message. For every attribute/relation you can select a name, what datatype it is, if it is required within the message and if it is multivalued. This contract should be set up to reflect the message that is send, but it can be different to you internal Blueriq domain. For instance, your contract uses a multivalued attribute. Your application always has one value for this attribute however, so it is not multivalued. When sending a message, it is no problem to insert a single-valued attribute in a multivalued entry in the domain schema. It will just be send as a list with only one entry. You have to be careful if it is the other way around, storing a list with possibly more values on a single values attribute.

In contrast to importing a WSDL, no service definition is automatically generated. You have to define how the REST service is called manually. Create a new REST service object and give your REST service a name.

Next, you need to specify the location of the REST service. This is an URL. You can already specify fragments and arguments here, but then you cannot change them later. For example, check http://services.faa.gov/airport/status/IAD?format=xml. In this case, airport, status and IAD are dynamic fragments and can change, depending on input by the user. You would only use http://services.faa.gov/ as location in this case.

Now you specify the Schema Set that you want to use. Choose the Schema Set that you have imported earlier.how the communication is specified. This can either be a domain schema, or an XSD schema set. You have to choose one XSD schema set here that has to include everything for the entire web service. In contrast, by choosing a domain schema, you will choose later what domain schema to use for every separate method.

Image AddedImage Removed

You can specify as many operations as you need, by pressing on the plus icon. Give every operation a unique name.

Request

If you want to dynamically change the address or send custom headers or body in your message, you need to specify a singleton entity from where the information is gathered (1). (2) shows the URL you are going to call. Items within {} are dynamic and determined at runtime. You can add static fragments (3) which are always the same, or dynamic fragments (4) which are filled by attributes of the request entity. You can specify arguments (5) of your request the same way. There are 4 different HTTP methods: GET, POST, PUT and DELETE. Most likely, the web service works with the GET method. This method does not alter the state of the web service and just asks for information. At (6) you specify what method to use.

Response

Now you can specify how your response message looks like. (1) lets you specify what kind of message it is (GET, POST, PUT or DELETE). If you need to set headers, then you can do so at (21) in the same way you set arguments or fragments earlierfor the request. If you need to send information in the body of the message, for example with a POST message, then you can specify this now. This screen looks different depending on if you send information using an XSD schema set or a domain schema.

We explain the XSD schema set first is done in XML, and your Schema needs to be able to handle this. If you have a SimpleType in the schema, then you fill in an attribute at (5). If it is a complexType, then first choose which entity will be sent at (3) and then your attribute field (5) will switch to a relation field. Fill in the name of the relation between your singleton request response entity and your data entity. Custom Schema Elements (4) are ways to fill in your schema in a different way other than with data from your profile. It is not needed at the moment (An example is a justification tree)

Image Added

When using a domain schema, you now simply select the domain schema that you want to use to send information (2). Furthermore, you have to select a body relation (3). This is a relation between the singleton response entity of your message and the entity that is chosen as the root entity in your domain schema.

Image AddedImage Removed