Wiki

Clone wiki

doc / FIspace System and Data Integration Module (SDI)

The FIspace System and Data Integration Module (SDI) serves the following two basic purposes:

  • SDI provides a standardized infrastructure to enable connection of external systems to the FIspace core platform, enabling them to be used as data or service providers in FIspace supported B2B workflows.

  • SDI provides the public API of the FIspace platform, which allows performing a variety of tasks in FIspace via REST web services. These REST services can either be called directly, or they can be used indirectly via additional tools, which are provided by FIspace to make their use more convenient.

According to these two basic purposes of SDI, the following documentation is separated into two main parts:

  1. Infrastructure for connection of external systems
  2. Public API of the FIspace platform

Infrastructure for connection of external systems

FIspace SDI provides a standardized infrastructure (interfaces plus communication protocol) to enable the connection of external systems to the FIspace core platform. The term “external systems” in this context may refer to a variety of different types of systems, for example:

  • business/legacy systems
  • IoT systems
  • backends of FIspace applications (providing the business logic of widgets in the FIspace Front-End)

Once these external systems are connected to SDI, they can be used as data or service providers in FIspace supported Business to Business (B2B) processes.

Aiming to abstract from the specific data interfaces of external systems, SDI supports the standardized definition of “capabilities” of external systems in the form of request and response messages. Capabilities of the same type can be implemented or instantiated by different companies, thus allowing competitors to provide the same type of services in a standardized format. The benefit of this approach is that all capabilities providing similar services have the same interface, allowing users to switch from one service to another with minimum adjustments to their software.

Typical communication flow when using capabilities via FIspace

A typical communication flow between external systems and FIspace takes place when one external system (Capability Consumer) wants to use a capability of another external system (Capability Provider) in the scope of a B2B process. During such a communication, FIspace is coordinating the request and response messages of capabilities. An example of a typical communication sequence is shown in the following figure. Please note that in order to enable this communication flow, the capabilities of the two external systems need to be registered in FIspace beforehand, and a business process definition is also required in order to "connect" the registered capabilities of Provider and Consumer.

SDI-Diagram.png

The depicted communication sequence is based on REST service calls, while the FIspace SDI communication protocol leads to an asynchronous communication between the external systems, controlled by FIspace. The steps of communication are the following:

  • At first the Capability Consumer sends the capability request message to FIspace using an HTTP POST call. FIspace answers with an HTTP 204 status code, which means that the message was received and will be further processed.
  • FIspace now determines to which external system that message is to be sent: the existing business process configuration defines to which Capability Provider the request should be addressed and the capability definition (registered by the Capability Provider) tells FIspace under which URL the Capability Provider's system can be reached. FIspace will send the request message to that URL via an HTTP POST call.
  • The Capability Provider's system processes the capability request message and generates the information that was asked for by the Capability Consumer. At this point of the communication sequence, two different situations are supported by the FIspace SDI communication protocol:
    • In case the requested information can be provided at once by the Capability Provider's system, it answers with an HTTP 303 - see other - and includes the URI where the advice can be collected by the Capability Consumer. This case is depicted in the figure above.
    • In case the requested information is not yet available and cannot be generated at once, the Capability Provider is allowed to answer with an HTTP 204 - no content. At a later time, when the requested information will be ready, the Capability Provider will send a so called "resource available notification" to FIspace (this case is not depicted in the figure).
  • Please note that in any case the Capability Provider does not send the actual information (requested by the Capability Consumer) to FIspace, but just the URI where the requested information can be collected. The aim of this approach is to support the protection of confidential business data by minimizing the amount of data passed through FIspace. The actual business data is then exchanged directly between the external systems.
  • FIspace now creates a "resource available notification" message (or forwards it in case the Capability Provider has sent one), which includes the URI provided by the Capability Provider, and sends it to the Capability Consumer's system via an HTTP POST. For this reason, the Capability Consumer's system needs to be registered in FIspace with a specific type of capability, namely the capability to receive such a "resource available notification" message.
  • The Capability Consumer's system can now ask the Capability Provider's system directly for the actual information, which is neither stored in nor sent through the FIspace platform.

Further details regarding the preconditions and the start of such a communication flow are explained in the following.

Preconditions/Setup for the capability usage via FIspace

Several preconditions have to be fulfilled In order to enable the communication flow between external systems and FIspace as described above. First and foremost a business process needs to be defined to “connect” different capabilities registered in FIspace. Therefore a short step-by-step guideline how to create a business process definition including capabilities is presented in the following (further details about the different steps are given in the second part of this SDI documentation (Public API of the FIspace platform) as well as in the SDK documentation):

  1. A Business Architect creates the business process flow definition in the form of a business process template. Two steps are required:

    • Firstly, reusing existing Capability Types or creating new ones, a Business Process Template has to be created, including the Capability Types involved in the process [See section How to Create a Business Process Template Example].

    • Secondly, the business flow needs to be defined and deployed in the BCM tool. The FIspace SDK provides the tools to perform these operations.

  2. Application Developers want to use an existing Business Process Template created by a Business Architect. They start by implementing the Capability Types that are included in the definition of the Business Process Template. To tell FIspace where to reach the external systems, the implemented Capabilities have then to be registered in SDI [See section How to Create a Capability Example].

  3. Application Developers or Users create a Business Process definition in SDI, including the necessary Capabilities. Each Business Process is based on a Business Process Template, which means that the Capabilities defined in the Business Process need to implement the Capability Types defined in the Business Process Template [See section How to Create a Business Process Example].

REST end points for Capability usage

The usage of a capability at business process runtime is done by sending capability request messages to FIspace via the SDI REST interface. SDI generates REST end-points dynamically: Each time a new capability type is registered, a new end-point is created, whose URI is built as follows:

http://{server}:{port}/sdi/api/capabilities/{CapabilityType.identifier}/use

The URI of the end point is based on the Capability Type identifier field, which has the following constraints:

  • Acceptable values: ([ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_])*
  • Maximum length is 100 characters
  • In case such an identifier is not provided while creating the capability type, the value of the name field will be used instead.

To invoke it, is necessary to send a POST method including the expected capability request message in the payload. The payload also has to include the id of the business process to use.

Starting the business process to use the capability

The actual run-time execution of a Business Process is explained in the following in the form of an example, based on the typical communication flow described above:

  • Let's assume that a customer wants to use a Capability provided by an expert system, which is defined in FIspace as follows:
<ns2:Capability xmlns:ns2="http://www.limetri.eu/schemas/ygg">
    <ns2:id>145</ns2:id>
    <ns2:description>green_house_advice capability of the expert system</ns2:description>
    <ns2:uri>http://37.131.251.169:8080/expert_system/api/receive_greenhouse_advice
    </ns2:uri>
    <ns2:cte_id>59</ns2:cte_id>
</ns2:Capability>
  • This Capability implements the following Capability Type with id 59 (<ns2:cte_id>59</ns2:cte_id>):
<ns2:capabilityType xmlns:ns2="http://www.limetri.eu/schemas/ygg">
    <ns2:id>59</ns2:id>
    <ns2:name>get greenhouse advice</ns2:name>
    <ns2:identifier>get_greenhouse_advice</ns2:identifier>
    <ns2:requestMessageType>GreenhouseAdviceRequest</ns2:requestMessageType>
    <ns2:responseMessageType>ResourceAvailableNotification</ns2:responseMessageType>
    <ns2:schemaLocation>classpath:/schema/domain/ag/AGMessages.xsd</ns2:schemaLocation>
    <ns2:contextPath>eu.limetri.ygg.api</ns2:contextPath>
</ns2:capabilityType>
  • Based on this capability type, SDI provides a REST end-point with the URI: http://{server}:{port}/sdi/api/capabilities/get_greenhouse_advice/use

  • Let's assume that a Business Process definition was registered in FIspace (based on an already existing Business Process Template) where the Capability of the expert system is linked with the customer's Capability to receive the Resource Available Notification [See section Typical communication flow when using capabilities via FIspace]. This business process is defined in FIspace as follows:

<ns2:businessProcess>
    <ns2:id>27</ns2:id>
    <ns2:name>green_house_advice business process</ns2:name>
    <ns2:bpt_id>32</ns2:bpt_id>
    <ns2:capabilities>
        <ns2:id>146</ns2:id>
        <ns2:description>receive_available_notification capability of the customer system</ns2:description>
        <ns2:uri>http://130.206.116.69:8080/resource/api/receive_available_notification</ns2:uri>
        <ns2:cte_id>4</ns2:cte_id>
    </ns2:capabilities>
    <ns2:capabilities>
        <ns2:id>145</ns2:id>
        <ns2:description>green_house_advice capability of the expert system</ns2:description>
        <ns2:uri>http://37.131.251.169:8080/expert_system/api/receive_greenhouse_advice</ns2:uri>
        <ns2:cte_id>59</ns2:cte_id>
</ns2:capabilities>
</ns2:businessProcess>
  • To start the execution of this business process, the initial capability request message needs to be sent by the customer system. This initial message also needs to include the ID of the registered Business Process (in this case 27 (<ns2:id>27</ns2:id>)).

How to start the execution of the Business Process

  • Send the capability request message to Fispace using a HTTP POST call to http://{server}:port}/sdi/api/capabilities/provide_greenhouse_advice/use

  • Example of a Payload to use (expected request message by Capability Type is GreenhouseAdviceRequest and Business Process to execute has ID 27):

<ns5:GreenhouseAdviceRequest xmlns:ns6="http://www.limetri.eu/schemas/ygg" xmlns:ns5="http://www.fispace.eu/domain/ag">
  <ns6:businessProcessId>27</ns6:businessProcessId>
  <FarmID>1</FarmID>
  <CropFieldID>1</CropFieldID>
  <Time>2015-09-18T14:33:07.684+02:00</Time>
</ns5:GreenhouseAdviceRequest>
  • Expected Response from FIspace is HTTP code 204 (No Content).

From this point on, FIspace will control the communication flow as described above [See section Communication flow between external systems and FIspace].

Data channels functionality: ability to trigger business processes using sensor data.

Besides starting a business process by sending a capability request message to FIspace (as described before), FIspace also offers the functionality to stream data to the FIspace platform and trigger business processes in case that specific conditions (patterns/events) occur in that data.

In order to send data to FIspace, a so called "channel" needs to be defined/created. A channel in FIspace represents a MQTT connection and topic to send data, which should be checked by Fispace for specific conditions.

Once a channel is created in FIspace, it is associated with the broker as a topic subscription only accessible by the user who has created the channel. To send data to FIspace, a client program must communicate with the broker, which is accessible under the same URI as SDI, but on a different port. For Java developers FIspace also offers tools (clients) to simplify the process to communicate with the broker.

A so called "trigger" represents a set of rules that FIspace should apply to the data received via a channel. Triggers are implemented as EPM configurations, i.e. when a "situation" is detected a business process will be triggered by EPM. The EPM configuration needs to be created using EPM tools and uploaded to the platform through SDI (detailed information about the creation and upload of EPM configurations can be found in the documentation about the FIspace B2B engine and the Fispace SDK). Please note that in order to be used, triggers have to be linked to data channels.

The next diagram depicts a general overview of this functionality. The upper part shows the steps to setup and configure channels and triggers (deployment part), while the lower part shows the communication at runtime.

channels-triggers.png

Java example below shows how to send data to FIspace through a channel:

//variables definition
private static final int BROKER_PORT = {broker_port};
YggMqttClient mqttClient;
YggClient sdiClient;

//methods implementation
public void setUp() {

   sdiClient = new YggClientInstalled("http://{server}:{port}/sdi/api", "http://{server}:{port}/sdi/admin-api")
   sdiClient.authenticate();

   String username = "XXXXXX";
   mqttClient = new YggMqttClient("http://{server}:{port}/sdi/api",
            "http://{server}:{port}/sdi/admin-api", BROKER_PORT, username, username);
}

public void testSendData() {

   //Object to send marshalled
   String xml = "<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns6:ReceiveSensorValuesRequestMessage xmlns:ns6="http://www.fispace.eu/domain/ag"xmlns:ns2="http://www.limetri.eu/schemas/ygg">....."

   mqttClient.sendData(sdiClient.getChannelRegistry().getChannel({channel_id}), xml);
}
  • Note: The example above refers to Java Programming Language. In case of using other Languages, be aware that it is needed to include a transformation in the Channel name to be aligned with MQTT broker: Data Channel name must be in LowerCase and with the following constraint replaceAll("[ \/\"'!@#$%^&*()]", "_");

Public API of the FIspace platform

The FIspace SDI provides the external/public API of the FIspace platform, implemented as Representational State Transfer (REST) services.

Please note that, for many of the operations supported by this API, FIspace provides additional tools or GUIs in order to make the access easier and more convenient, e.g.:

  • The FIspace Front-End provides some GUI forms to do typical SDI operations like registering a capability.
  • The SDK allows to upload developed apps or configurations to FIspace store directly from the IDE.
  • For Java developers Fispace provides the so called YGG client as a convenience method to access many operations in the SDI API.

Although there is always the option to use the API directly, it is in general recommended to use the tools mentioned above. In the following subsections, each operation is explained, giving also an example of the payloads of the REST calls.

Managing Capability Types

The next table shows the API operations offered to manage capability types:

Method URL (http://{server}:{port}/sdi) Description
GET /admin-api/capability-types Retrieves a list of existing Capability Types
GET /admin-api/capability-types/{id} Gets a Capability Type for specified id
PUT /admin-api/capability-types Creates a Capability Type
DELETE /api/capability-types/{id} Removes a Capability Type

Please note: instead of using this REST API directly, it is also possible to use the FIspace Front-end, which provides a graphical UI to manage capability types.

How to Create a Capability Type Example

  • User must have Business Architect Role

  • Send PUT method to http://{server}:{port}/sdi/admin-api/capability-types

  • Payload:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<capabilityType xmlns="http://www.limetri.eu/schemas/ygg">
  <name>HowToCreateCapabilityType</name>
  <identifier>identifier</identifier>
  <requestMessageType>GreenhouseAdviceRequest</requestMessageType>
  <responseMessageType>ResponseMessage</responseMessageType>
  <schemaLocation>classpath:/schema/domain/ag/AGMessages.xsd</schemaLocation>
  <contextPath>eu.fispace.api.ag</contextPath>
</capabilityType>
  • Expected Response: 200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:capabilityType
    xmlns:ns2="http://www.limetri.eu/schemas/ygg">
    <ns2:id>63</ns2:id>
    <ns2:name>HowToCreateCapabilityType</ns2:name>
    <ns2:identifier>identifier</ns2:identifier>
    <ns2:requestMessageType>GreenhouseAdviceRequest</ns2:requestMessageType>
    <ns2:responseMessageType>ResponseMessage</ns2:responseMessageType>
    <ns2:schemaLocation>classpath:/schema/domain/ag/AGMessages.xsd</ns2:schemaLocation>
    <ns2:contextPath>eu.fispace.api.ag</ns2:contextPath>
</ns2:capabilityType>

Managing Business Process Templates

The next table shows the API operations offered to manage business process templates:

Method URL (http://{server}:{port}/sdi) Description
GET /admin-api/business-process-templates Retrieves a list of existing Business Process Templates
GET /admin-api/business-process-templates/{id} Gets a Business Process Template for specified id
PUT /admin-api/business-process-templates Creates a Business Process Template
DELETE /api/business-process-templates/{id} Removes a Business Process Template

Please note: instead of using this REST API directly, it is also possible to use the FIspace Front-end, which provides a graphical UI to manage business process templates.

How to Create a Business Process Template Example

  • User must have Business Architect Role

  • Send PUT method to http://{server}:{port}/sdi/admin-api/business-process-templates

  • Payload:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BusinessProcessTemplate xmlns="http://www.limetri.eu/schemas/ygg">
    <name>HowToCreateBusinessProcessTemplate</name>
    <capabilityTypes>
        <id>4</id>
        <name>receive resource available notification</name>
        <identifier>receive_resource_available_notification</identifier>
        <requestMessageType>ResourceAvailableNotification</requestMessageType>
        <responseMessageType>Untyped</responseMessageType>
        <schemaLocation>classpath:/eu/limetri/ygg/schema/yggModel.xsd</schemaLocation>
        <contextPath>eu.limetri.ygg.api</contextPath>
    </capabilityTypes>
    <capabilityTypes>
        <id>59</id>
        <name>get greenhouse advice</name>
        <identifier>get_greenhouse_advice</identifier>
        <requestMessageType>GreenhouseAdviceRequest</requestMessageType>
        <responseMessageType>ResourceAvailableNotification</responseMessageType>
        <schemaLocation>classpath:/schema/domain/ag/AGMessages.xsd</schemaLocation>
        <contextPath>eu.limetri.ygg.api</contextPath>
    </capabilityTypes>
</BusinessProcessTemplate>
  • Expected Response: 200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:BusinessProcessTemplate
    xmlns:ns2="http://www.limetri.eu/schemas/ygg">
    <ns2:id>33</ns2:id>
    <ns2:name>HowToCreateBusinessProcessTemplate</ns2:name>
    <ns2:capabilityTypes>
        <ns2:id>4</ns2:id>
        <ns2:name>receive resource available notification</ns2:name>
        <ns2:identifier>receive_resource_available_notification</ns2:identifier>
        <ns2:requestMessageType>ResourceAvailableNotification</ns2:requestMessageType>
        <ns2:responseMessageType>Untyped</ns2:responseMessageType>
        <ns2:schemaLocation>classpath:/eu/limetri/ygg/schema/yggModel.xsd</ns2:schemaLocation>
        <ns2:contextPath>eu.limetri.ygg.api</ns2:contextPath>
    </ns2:capabilityTypes>
    <ns2:capabilityTypes>
        <ns2:id>59</ns2:id>
        <ns2:name>get greenhouse advice</ns2:name>
        <ns2:identifier>get_greenhouse_advice</ns2:identifier>
        <ns2:requestMessageType>GreenhouseAdviceRequest</ns2:requestMessageType>
        <ns2:responseMessageType>ResourceAvailableNotification</ns2:responseMessageType>
        <ns2:schemaLocation>classpath:/schema/domain/ag/AGMessages.xsd</ns2:schemaLocation>
        <ns2:contextPath>eu.limetri.ygg.api</ns2:contextPath>
    </ns2:capabilityTypes>
</ns2:BusinessProcessTemplate>

Managing Capabilities

The next table shows the API operations offered to manage capabilities:

Method URL (http://{server}:{port}/sdi) Description
GET /admin-api/capabilities Retrieves a list of existing Capabilities
GET /admin-api/capabilities/{id} Gets a Capability for specified id
PUT /admin-api/capabilities Creates a Capability
DELETE /api/capabilities/{id} Removes a Capability

Please note: instead of using this REST API directly, it is also possible to use the FIspace Front-end, which provides a graphical UI to manage capabilities.

How to Create a Capability Example

  • User must have Application Developer Role

  • Send PUT method to http://{server}:{port}/sdi/admin-api/capabilities

  • Payload:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Capability xmlns="http://www.limetri.eu/schemas/ygg">
  <description>HoToCreateCapability</description>
  <uri>http://37.131.251.169:8080/expert_system/api/receive_greenhouse_advice</uri>
  <cte_id>59</cte_id>
</Capability>
  • Expected Response: 200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:Capability
    xmlns:ns2="http://www.limetri.eu/schemas/ygg">
    <ns2:id>190</ns2:id>
    <ns2:description>HoToCreateCapability</ns2:description>
    <ns2:uri>http://37.131.251.169:8080/expert_system/api/receive_greenhouse_advice</ns2:uri>
    <ns2:cte_id>59</ns2:cte_id>
</ns2:Capability>

Managing Business Processes

The next table shows the API operations that are offered to manage business processes:

Method URL (http://{server}:{port}/sdi) Description
GET /admin-api/business-processes Retrieves a list of existing Business Processes
GET /admin-api/business-processes/{id} Gets a Business Process for specified id
PUT /admin-api/business-processes Creates a Business Process
DELETE /api/business-processes/{id} Removes a Business Process

Please note: instead of using this REST API directly, it is also possible to use the FIspace Front-end, which provides a graphical UI to manage business processes.

How to Create a Business Process Example

  • User must have User Role

  • Send PUT method to http://{server}:{port}/sdi/admin-api/business-processes

  • Payload:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<BusinessProcess xmlns="http://www.limetri.eu/schemas/ygg">
  <id>26</id>
  <name>HowToCreateBusinessProcess</name>
  <bpt_id>32</bpt_id>
    <capabilities>
      <id>146</id>
      <description>receive_green_house_advice_bremen</description>
      <uri>
      http://130.206.116.69:8080/resource/api/receive_available_notification
      </uri>
      <cte_id>4</cte_id>
    </capabilities>
    <capabilities>
      <id>145</id>
      <description>green_house_advice_bremen_</description>
      <uri>
      http://37.131.251.169:8080/expert_system/api/receive_greenhouse_advice
      </uri>
      <cte_id>59</cte_id>
    </capabilities>
</BusinessProcess>
  • Expected Response: 200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:BusinessProcess
    xmlns:ns2="http://www.limetri.eu/schemas/ygg">
    <ns2:id>28</ns2:id>
    <ns2:name>HowToCreateBusinessProcess</ns2:name>
    <ns2:bpt_id>32</ns2:bpt_id>
    <ns2:capabilities>
        <ns2:id>146</ns2:id>
        <ns2:description>receive_green_house_advice_bremen</ns2:description>
        <ns2:uri>http://130.206.116.69:8080/resource/api/receive_available_notification</ns2:uri>
        <ns2:cte_id>4</ns2:cte_id>
    </ns2:capabilities>
    <ns2:capabilities>
        <ns2:id>145</ns2:id>
        <ns2:description>green_house_advice_bremen_</ns2:description>
        <ns2:uri>http://37.131.251.169:8080/expert_system/api/receive_greenhouse_advice</ns2:uri>
        <ns2:cte_id>59</ns2:cte_id>
    </ns2:capabilities>
</ns2:BusinessProcess>

Managing Channels

This operation is extremely recommended to be performed using the FIspace Frontend. API offered by SDI as follows:

Method URL (http://{server}:{port}/sdi) Description
GET /admin-api/channels Retrieves a list of existing Channels
GET /admin-api/channels/{id} Gets Channel for specified id
POST /admin-api/channels Creates a Channel
PUT /admin-api/channels/{id} Updates a Channel
DELETE /api/channels/{id} Removes a Channel

How to Create a Channel Example

  • User must have Application Developer Role

  • Send POST method to http://{server}:{port}/sdi/admin-api/channels

  • Payload:

<Channel xmlns="http://www.limetri.eu/schemas/ygg">
  <name>HowToCreateChannels</name>
  <format>application/xml</format>
  <contextPath>eu.fispace.api.ag</contextPath>
</Channel>
  • Expected Response: 200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:Channel
    xmlns:ns2="http://www.limetri.eu/schemas/ygg">
    <ns2:id>52</ns2:id>
    <ns2:name>HowToCreateChannels</ns2:name>
    <ns2:format>application/xml</ns2:format>
    <ns2:contextPath>eu.fispace.api.ag</ns2:contextPath>
</ns2:Channel>

Managing Triggers

This operation is extremely recommended to be performed using the FIspace Frontend. API offered by SDI as follows:

Method URL (http://{server}:{port}/sdi) Description
GET /admin-api/triggers Retrieves a list of existing Triggers
GET /admin-api/triggers/{id} Gets a Trigger for specified id
POST /admin-api/triggers Creates a Trigger
PUT /admin-api/triggers/{id} Updates a Trigger
DELETE /api/triggers/{id} Removes a Trigger

How to Create a Trigger Example

  • User must have Application Developer Role

  • Send POST method to http://{server}:{port}/sdi/admin-api/triggers

  • Payload:

<Trigger xmlns="http://www.limetri.eu/schemas/ygg">
  <name>TriggerCreationTest</name>
  <triggerCondition>{EPM configuration file here}</triggerCondition>
  <channelId>{channelID}</channelId>
  <businessProcessId>{businessProcessID}</businessProcessId>
</Trigger>
  • Expected Response: 200 OK
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:Trigger
    xmlns:ns2="http://www.limetri.eu/schemas/ygg">
    <ns2:id>56</ns2:id>
    <ns2:name>HowToCreateTriggers</ns2:name>
    <ns2:triggerCondition>{EPM configuration file here}</ns2:triggerCondition>
    <ns2:businessProcessId>{businessProcessID}</ns2:businessProcessId>
    <ns2:channelId>52</ns2:channelId>
</ns2:Trigger>

Managing app widgets in the FIspace store

SDI offers the external API to register widgets in the store component of FIspace. The available operations are:

Method URL (http://{server}:{port}/sdi-store) Description
GET /api/appRegistration/{name}/{version} Retrieves the status of an uploaded widget
POST /api/appRegistration Creates an offerning in WStore
PUT /api/appRegistration Updates an offerning in WStore
DELETE /api/appRegistration/{name}/{version} Deletes an widget

How to Register an App Example

Although this operation is strongly recommended to be executed through SDK, relevant information regarding this operation is also provided: Message involved in the process is AppRegistration Message, available in the StoreModel of FIspace API. Below it is depicted an example of a message to upload widget to FIspace platform and the link to the XSD definition:

  • Send POST method to http://{server}:{port}/sdi-store/api/appRegistration/

  • Payload:

<AppRegistration>
    <app>
        <name>WidgetUpload</name>
        <version>1.0</version>
        <resource>http://fispace:fispace@store-pie.fispace.eu:8082/nexus/service/local/repositories/Fispace/content/eu/fispace/apps/W_preferences/1.0/W_preferences-1.0.war</resource>
        <description>Testing Widget Upload</description>
        <status>New</status>
    </app>
</AppRegistration>
  • Expected Response: 200 OK

XSD here: https://bitbucket.org/fispace/core/src/dba758211c24b1acd17bf7c30034781d11412be0/api/src/main/resources/schema/domain/admin/StoreMessages.xsd?at=default&fileviewer=file-view-default

Managing BCM Configurations

SDI offers the external API of the BCM module to upload BCM configurations. The available API operations are shown in the following table:

Method URL (http://{server}:{port}/sdi-b2bconf) Description
GET /api/BCMConf/{package}/{name} Retrieves the status of an uploaded BCM configuration
POST /api/BCMConf Uploads a BCM configuration
PUT /api/BCMConf Updates an uploaded BCM configuration
DELETE /api/BCMConf/{package}/{name} Deletes an uploaded BCM configuration

How to Upload a BCM Configuration Example

Although this operation is strongly recommended to be executed through SDK, relevant information regarding this operation is also provided: Message involved in the process is BCMConf Message, available in the StoreModel of FIspace API. Below it is depicted an example of a message to upload a BCM configuration and the link to the XSD definition:

  • Send POST method to http://{server}:{port}/sdi-b2bconf/api/BCMConf/

  • Payload:

<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>
<BCMConf xmlns:ns2=\"http://www.fispace.eu/domain/common\">
    <conf>
        <name>BCMconfToUpload</name>
        <package>AG</package>
        <status>New</status>
        <zipfileACSI>{File in Base64.encodeBase64 format}</zipfileACSI>
        <zipfileBridge>{File in Base64.encodeBase64 format}</zipfileBridge>
    </conf>
</BCMConf>
  • Expected Response: 200 OK

XSD here: https://bitbucket.org/fispace/core/src/dba758211c24b1acd17bf7c30034781d11412be0/api/src/main/resources/schema/domain/admin/StoreMessages.xsd?at=default&fileviewer=file-view-default

Sending Notifications

SDI offers the external API of the FIspace Frontend in order to use the Notification Service. The API operation is:

Method URL (http://{server}:{port}/sdi-frontend) Description
POST /api/notification Sends a notification to a FIspace User

Although this operation is strongly recommended to be executed through SDK, relevant information regarding this operation is also provided: Communication Message involved in the process is Notification Message, available in the AdminModel of FIspace API. Below it is depicted an example of a message to send a notification and the link to the XSD definition:

  • Send POST method to http://{server}:{port}/sdi-frontend/api/notification

  • Payload:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Notification xmlns:ns2="http://www.fispace.eu/domain/common">
  <NotificationInfo>
    <fispaceUserId>{username}</fispaceUserId>
    <type>alert</type>
    <message>Testing Notification</message>
  </NotificationInfo>
</Notification>
  • Expected Response: 200 OK

XSD here: https://bitbucket.org/fispace/core/src/dba758211c24b1acd17bf7c30034781d11412be0/api/src/main/resources/schema/domain/admin/AdminMessages.xsd?at=default&fileviewer=file-view-default

Updated