# Integration services

The recommended way to communicate with Tempus Serva is through the webservice interface (REST).

Regardless of you are using the scheduled import services or the webservice interface, all restrictions from the solution models apply.

# Scheduled data imports

The services runs in the context of a user (static), that can have restricted access just as any other user.

# Database connection / SQL

Databases fields are mapped to solution fields by their SQL names.

The SQL import allows for incremential imports, by adding a datetime filter on the records extracted.

Connections for the remote database is set up in: **Designer > Integration > DB Connections**

# CSV file import

CSV imports are handled much in the same way as SQL connections using af CSV database driver.

The differences are

- Use the filename as substitute for the table name
- Files have to be placed in the folder set by the configuration: **folderIntegrationCSV**
- Support for very simple WHERE clauses
- No support for aggregate functions

# Parsing XML data files

XML fields are mapped to solution fields by xpath expressions.

XML integration also handles task splitting and handling. Each file is split into multiple smaller requests, that are logged and handled individually. In that way an error in a single line, will not prevent the complete batch from executing. The task split is done by an xpath expression.

Files are split in the following folder structure

- Tasks that are **awaiting** processing
- Tasks that have been processed 
    - Tasks processed with **succes**
    - Tasks processed with **errors**

This allows for easy resubmission of problem data ("Tasks processed with errors"), by copying the file back to the preocessing folder ("Tasks awaiting processing").

Files have to be placed in the folder set by the configuration: **folderIntegrationXML**

# Converting emails to data

The email import converts new emails sent to a certain account.

A few special email "values" can be mapped to solution fields

- Email: Senders address
- Subject: Email subject title line (text)
- Content: Text payload in email (rich text)
- Attatchments: Files attached to the email

After processing the emails they are marked as read at the server - regardless of succes/error status. Reprocessing can be invoked by changing the read status of the email in question.

# Content source (aka CMS data delivery)

The content delivery service can serve any view for external systems (for example: your website).

The content interface serves in different formats (json,html,xml), and provides a caching mechanism too.

# Setting up a content source

THIS ARTICLE IS UNDER DEVELOPMENT<span class="mw-headline" id="bkmrk-setting-up-a-content-1"></span>

Many parameters are straight forward

- Related solution
- Max cache age
- Is active

### <span class="mw-headline" id="bkmrk-unique-name-1">Unique NAME</span>

This is the calling name of the interface, that must be provided accessing the content service.

Example for calling the view **myview**

```
.../cmsinterface?q=myview& ...
```

### <span class="mw-headline" id="bkmrk-query-command-1">Query command</span>

Relevant commands include

- General records 
    - list: List of records
    - show: Single record
- HTML formatted views 
    - heat: Heatmaps
    - gant: Gant charts
    - xtab: Pivot tables
    - calm: Calendar

### <span class="mw-headline" id="bkmrk-query-parameters-1">Query parameters</span>

Parameters are provided without URL encoding

```
QUERY_FIELD_1=TITEL&QUERY_OPERATOR_1=8&QUERY_VALUE_1=Hello&QUERY_SHOWFIELD=TITEL StatusID DEADLINE
```

Procedure for easy parameter setup

1. Build views in frontend.
2. Activate the link and copy the URL
3. ´Remove unneeded parameters 
    - command
    - SagID
    - QUERY\_NEW

### <span class="mw-headline" id="bkmrk-possible-parameters-1">Possible parameters</span>

<table id="bkmrk-query_field_n-part-o"><tbody><tr><td>QUERY\_FIELD\_n</td><td>Part of the search/filter. The field to filter by.</td></tr><tr><td>QUERY\_OPERATOR\_n</td><td>Part of the search/filter. The way to filter. Full list [Dashboard widget configuration](https://docs.tsnocode.com/books/dashboards/chapter/dashboard-widget-configuration-Ulo "Dashboard widget configuration")</td></tr><tr><td>QUERY\_VALUE\_n</td><td>Part of the search/filter. The value to filter by.</td></tr><tr><td>QUERY\_SHOWFIELD</td><td>The fields to show in the list, separated by space.</td></tr><tr><td>QUERY\_PageSize</td><td>Number of records to show pr page.</td></tr><tr><td>QUERY\_PageOffset</td><td>The page number to show.</td></tr><tr><td>QUERY\_SortOrder</td><td>The field to sort ascending by. Use either this or SortOrderDesc.</td></tr><tr><td>QUERY\_SortOrderDesc</td><td>The field to sort descending by. Use either this or SortOrder.</td></tr><tr><td>QUERY\_Grouping</td><td>The field to group records by.</td></tr><tr><td>QUERY\_GroupingDesc</td><td> </td></tr></tbody></table>

### <span class="mw-headline" id="bkmrk-dynamic-parameter-1">Dynamic parameter</span>

This specifies a parameter that will be set by the value provided in the **v** parameter.

Example: Using this interface

```
Unique NAME: mylist
Query command: list
Dynamic parameter: QUERY_PageOffset
```

Making a call to

```
.../cmsinterface?q=mylist&v=2
```

Will fetch a list of data and display page 2, because **2** is injected into **QUERY\_PageOffset**.

Parameters and values are injected directly into the http request.

**Note: Using the "show" command the variable will ALLWAYS get mapped to "DataID"**

## <span class="mw-headline" id="bkmrk-using-a-content-sour-1">Using a content source</span>

Calling the **cmsinterface** servlet will provide you with an overview on how to use it.

Example:

```
https://www.acme.com/TempusServa/cmsinterface
```

The interface requires just the name of the source, but additional parameters can be provided.

Parameters

- **q**: Name of the interface (required) 
    - This name must match "Unique NAME"
- **f**: Format of the result (optional) 
    - Valid values: html json xml
- **v**: Parameter for dynamic values (optional) 
    - The value will be substituted to the parameter in "Dynamic parameter"

Example:

```
https://www.acme.com/TempusServa/cmsinterface?q=mysource&f=json
```

## <span class="mw-headline" id="bkmrk-troubleshooting-1">Troubleshooting</span>

THIS ARTICLE IS UNDER DEVELOPMENT

### <span class="mw-headline" id="bkmrk-configuration-cachin-1">Configuration caching</span>

For performance reasons information about the content sources is kept cached.

Adding or changing sources will propegate automatically : You will need to clear the system cache to pick the changes.

### <span class="mw-headline" id="bkmrk-parameter-encoding-1">Parameter encoding</span>

Note that URL's copied from a browser address bar are often encoded in HTML format.

The content will not decode values and request strings, so all encoded strings will fail.

# Consuming a Content Source

## <span class="mw-headline" id="bkmrk-cms-content-provider-1">CMS content provider</span>

The CMS connector will allow CMS systems to extract information from a TempusServa system, and display it inline in other pages.

Example:

```
Data extracted from the Tempus Serva connector
http://alpha.tempusserva.dk/TempusServa/cmsinterface?q=examdates
```

```
The final result inside a page in our website
http://tempusserva.dk/site/index.php/da/eksamensdatoer
```

  
Notes on usage

- A CMS system is no requirement and static HTML files will work too.
- The TS backend will not be slowed because all content is cached in the connector (configurable)
- Connectors have NO influence on licensing

## <span id="bkmrk-"></span><span class="mw-headline" id="bkmrk-tempus-serva-setup-%28-1">Tempus Serva setup (provider)</span>

Frontend

1. Make the request that suits your needs 
    - Filters and parameters
    - Sorting / grouping
    - Fields to display
    - Fields to display
    - Page size
2. Save the view
3. Click on the view and copy the parameters

Backend

1. Check that anonumous users have the right permissions 
    - Note the interface will only allow READ operations
2. Go to "Integration" &gt; "Content connector"
3. Add new element 
    1. Give the connector a unique name (CONNECTOR\_NAME&gt;)
    2. Choose solution and set command type (as seen in the "command" parameter in the URL)
    3. Paste alle parameters from the URL above 
        - Optionally add other settings like Language and Stylesheet
    4. Optionally define a variable that the "v" parameter will be mapped to (OPTIONAL\_VARIABLE)
4. Test the new connector

  
URL format

- http://myserver.dk/TS/**cmsinterface?q=**&lt;CONNECTOR\_NAME&gt;
- http://myserver.dk/TS/**cmsinterface?q=**&lt;CONNECTOR\_NAME&gt;**&amp;v=**&lt;OPTIONAL\_VARIABLE&gt;

  
Example URL's

- http://myserver.dk/TS/**cmsinterface?q=customerList&amp;v=3**
- http://myserver.dk/TS/**cmsinterface?q=longActivityList&amp;v=3**
- http://myserver.dk/TS/**cmsinterface?q=singleActivityById&amp;v=782382386**

Note that links between lists and single items will first be supported by Q2/2014.

## <span id="bkmrk--1"></span><span class="mw-headline" id="bkmrk-cms-system-setup-%28co-1">CMS system setup (consumer)</span>

### <span class="mw-headline" id="bkmrk-option%3A-client-rende-1">Option: Client rendering</span>

The following procedure

1. Make sure JQuery is available (normal JS can do the job)
2. Insert content placeholder and Javascript code

<div class="tsContent" id="bkmrk--2"></div>```html
<script>
  jQuery.ajax(
  { 
    url: 'http://myserver.com/TempusServaProxy.php?q=examdates', 
    success: function(data) { jQuery('#tsContent').html(data); } 
   });
</script>
```

Note: The URL above reflects the use of a proxy script (see below).

### <span class="mw-headline" id="bkmrk-option%3A-server-side--1">Option: Server side include</span>

Insert code that fetches the content

```php
echo file_get_contents("http://myserver.com/TS/cmsinterface?q=examdates")
```

In some cases you might want to remove the wrapper, header etc. from normal pages. This is done by adding the AjaxMode parameter.

```php
echo file_get_contents("https://talentpiper.com/demo/mainpublic?command=dk.p2e.blanket.codeunit.common.PagePublicRecordsListAndShow&AjaxMode=1");
```

Note: The URL above reflects the direct use of interface.

### <span class="mw-headline" id="bkmrk-overcoming-cors-prot-1">Overcoming CORS protection</span>

I cases where the TempusServa server and the CMS system is on different domains (ex. acme.shared.com and cms.acme.com), browsers will prevent pages from accessing content from other servers.

Two options exist

1. Use server side includes (ok, but not supported everywhere)
2. Set up a mini proxyserver

A mini proxyserver written i PHP is very simple (aspx/jsp will have similar features) and placed on the CMS side.

```php
<?php 
echo file_get_contents("http://myserver.dk/TS/cmsinterface?q=".$_GET["q"]."&v=".$_GET["v"]);
```

The proxy can also be deployed on another domain than the CMS system.

```php
<?php 
header("Access-Control-Allow-Origin: *");
echo file_get_contents("http://myserver.dk/TS/cmsinterface?q=".$_GET["q"]."&v=".$_GET["v"]);
```

For a more safe version write the name of the CMS domain

```php
header("Access-Control-Allow-Origin: www.tempusserva.dk");
```

Afterwards you just make the calls through the proxy using exact same parameters.