XWiki Integration

Last modified on 2022/11/08 13:22

SM_IntegrationIntroduction_OnlyEN

You can integrate third-party systems with Service Manager in many ways. The method you select will depend on business requirements, architectural and security constraints as well as the characteristics specific to each third-party application or service.

This document describes an integration process that has already been implemented in a customer context. 

To find out more about this integration (e.g. scripts to be used), please do not hesitate to contact your EasyVista contact, or your service provider and integrator.

Integration Summary

This integration is used to retrieve all available information from your XWiki domain using the XWiki REST API (GET method).

example    Retrieve and display in an Service Apps app a list of all wiki pages (including their name and URI) in a particular space of a particular wiki or from all spaces or wikis answering certain criteria (pages containing specific keywords, etc.)

Integration Data Feed (direction) Authentication Type Integration Connector Options

Favicon EasyVista - 32.png Service Apps

Up arrow.png

Logo - XWiki.png

Check icon.png   Basic Access Authentication

REST data source   Apps - Datasource - JSON Online icon.png

SaaS Version of Third-Party Product

On-premise Version of Third-Party Product

Check icon.png

Check icon.png

API detailed description

Item Comments
About the software and company

Logo - XWiki.png

XWiki is a free wiki software platform written in Java with a design emphasis on extensibility. XWiki Enterprise, the enterprise wiki edition, includes WYSIWYG editing, OpenDocument based document import/export, semantic annotations and tagging, and advanced permissions management.

Information about the REST API

Date on which the information was retrieved from the software company's website: March 2016

Last known REST API name/version/date: XWiki RESTful API

Note: Other APIs that can be used:

Main useful links to software company information about REST

XWiki REST API Introduction

XWiki REST API References

Format and sample of API resources/endpoints For SaaS version:
  • By default the XWiki RESTful API entrypoint is rooted at the following URI: https://{subdomain}/xwiki/rest/

    ==> https://{subdomain}/xwiki/rest/wikis/{wikiName}/spaces/{nestedSpaceName}/pages

example For  EasyVista wiki called wiki and the space Documentation accessible by all Internet users:

==> https://wiki.easyvista.com/xwiki/rest/wikis/wiki/spaces/Documentation/pages

  • To retrieve content in JSON format:

    https://{subdomain}/xwiki/rest/wikis/{wikiName}/spaces/{nestedSpaceName}/pages?media=json

For On-premises version:
  • By default all the resources of the RESTful API are rooted at the following URI: http://{host:port}/xwiki/rest/

    ==> http://{host:port}/xwiki/rest/wikis/{wikiName}/spaces/{nestedSpaceName}/pages

example For a wiki on your localhost called  wiki123 with a space Documentation:

==> http://localhost:8080/xwiki/rest/wikis/wiki123/spaces/Documentation/pages

  • To retrieve content in JSON format:

    http://{host:port}/xwiki/rest/wikis/{wikiName}/spaces/{nestedSpaceName}/pages?media=json

Notes:
  • When documenting a resource, XWiki uses curly brackets { } for identifiers.
  • Replace in the URI:
    • {subdomain} with your subdomain name provided by XWiki.
    • {wikiName} and {nestedSpaceName} with the name of the specific wiki and the name of the specific space for which you want to execute API calls.
    • {host:port} with the location of your server hosting XWiki.
API assets
  • A "HATEOAS" graph in order to better understand the relations among resources
  • Possibility to execute queries using other XWiki APIs (HQL, XWQL, Lucene or SOLR queries):

    https://{subdomain}/xwiki/rest/wikis/{wikiName}/query?q={query}&type={hql,xwql,lucene,solr}[&distinct={true,false}][&order={asc,desc}][&start=n][&number=n][&prettyNames={true,false}][&className=className]

API recommendations (limitations, advice, tips)
  • API calls: No information available/found
  • Pagination: /wikis/{wikiName}/spaces[?start=offset&number=n]
Comments
  • No API versioning
  • The total number of records is not returned in the JSON file

Step-by-step integration process

XWiki can be integrated with Service Apps in 4 easy steps:


Step 1: Check the list of prerequisites

  • This documentation assumes that you already have a XWiki domain/platform or On-premises server.


Step 2: Start the process for creating the REST data source

  Open url.png  For details about the creation, see the wiki page REST data source

  • Click Apps - Add datasource icon.png in the Objects pane
  • Open the Online category and select the REST data source Apps - Datasource - JSON Online icon.png.
  • Name the data source.

    example  XWiki_List of Pages


Step 3: Authenticate to XWiki

Authenticate with Basic Access Authentication

  • Select the type of authentication: Authentication Type = Basic.
  • Click Apps - Edit icon.png next to the Basic Authentication Parameters field. 
  • Enter the User Name using the following format: firstname.lastname@company.com. Enter the Password.
             Basic Access Authentication.png
    • The user name is the XWiki account/login (with Admin credentials) you want to use for this data source. 
    • The password is the password set for this account.
    • Once you validate, the *** symbols will appear in the field.


Step 4: Create a query string using XWiki documentation

        Open url.png  See the XWiki REST API References (endpoints)
        Open url.png  See Examples of use cases

  • Create a query string as a data source, i.e. a resource to access, in the URL field.

example    You want to create a data source that will retrieve the list of all wiki pages (including their URI) in a particular space of a particular wiki  ==>  Enter the following text in the URL field. Note: Replace {subdomain} with the name of your XWiki instance.

https://{subdomain}/xwiki/rest/wikis/{wikiName}/spaces/{nestedSpaceName}/pages?media=json

Best Practice

       Open url.png  See Best Practice for the REST data source

  • You must keep all information on credentials secure.

Samples of most relevant use cases and resources

Note: Replace in the URI: 

  • {subdomain} with your subdomain name provided by XWiki.
  • {wikiName} and {nestedSpaceName} with the name of the specific wiki and the name of the specific space for which you want to execute API calls. 

Method: GET

Use Case Sample Endpoint
Retrieve the list of wikis available on the XWiki instance

Note: Unless the wiki is configured to be a wiki farm, this list is usually made of a single element xwiki.

Authentication Type: Basic Access Authentication
Basic Authentication Parameters: User Name: {email_address}

Password: {password}

URI: https://{subdomain}.xwiki/rest/wikis?media=json
Selector: N/A
Retrieve the list of all wiki pages (including their URI) in a particular space of a particular wiki

Authentication Type: Basic Access Authentication
Basic Authentication Parameters: User Name: {email_address}

Password: {password}

URI: https://{subdomain}/xwiki/rest/wikis/{wikiName}/spaces/{nestedSpaceName}/pages?media=json
Selector: N/A
Retrieve the list of wiki pages and objects that contain:
  • specific {keywords}
  • in specified {scopes}
  • with results sorted out in ascending order

Authentication Type: Basic Access Authentication
Basic Authentication Parameters: User Name: {email_address}

Password: {password}

URI: https://{subdomain}.xwiki/rest/wikis/{wikiName}/search?q={Keywords}&scope=name,content,title,objects&order=asc&media=json

Note: Replace {Keywords} with the keywords for which you want to get pages.

example For keyword =  Rest Data Source and scopes = name and content

==> https://{subdomain}.xwiki/rest/wikis/{wikiName}/search?q=Rest%20Data%20Source&scope=name,content&order=asc&media=json

Selector: N/A
SAS_IntegrationRESTAboutTheUse_OnlyEN

About the use of the software companies API REST

   Caution : The possible cost of the use of the third-parties API REST via Service Apps is not taken care by EasyVista.

  • Numerous software companies limit the access to the API REST of their software, generally by basing itself on a number of calls by hour/day/month.
  • Only specific editions of their software can be eligible in the use of the API REST (with or without additional cost).
  • Some software companies set up plans, e.g., Classic, Professional, Enterprise, for which the number of possible calls to the REST API or even to specific resources (i.e. endpoints) can be more or less numerous.
Tags:
Powered by XWiki © EasyVista 2022