The Xillio API provides a platform with which developers can effortlessly build integrations with all popular content repositories, making content stored in both cloud content systems and legacy systems accessible from any application.
The core functionality of the Xillio API is to create, retrieve, manipulate and delete content no matter where it is stored. This is done by defining a set of operations which can be performed on every repository agnostically.
1. REST API
This section describes the second version of the official Xillio API. It defines the different endpoints of the API and the URL schema used. The way errors are handled and returned is also explained in this section.
1.1. Overview
The root endpoint of this API is https://{tenant}.xill.io/v2.
This URL denotes that this API is currently in version 2 (v2) and works over HTTPS.
Every tenant uses their own endpoint.
This means {tenant} should be substituted by your tenant name.
For example, if your tenant name is demo-tenant then your base URL would be https://demo-tenant.xill.io/v2.
To locate documents in a repository, an internal protocol called XDIP is used.
The request URL is based on this XDIP.
The XDIP and the request URLs are connector-specific.
Therefore the request URLs should not be hand-crafted, but instead obtained by browsing the target repository through the API.
This can be done by starting at the root entities endpoint and requesting a relation scope (e.g. path_children_reference).
The id field of an entity can be used to request that entity.
This id field looks like this: https://{tenant}.xill.io/v2/entities/{configurationId}/{path}.
In this document, the id of an entity can also be referred to as its URL.
|
When the API returns an id, it always points to the latest version of an entity.
Therefore, when a newer version of that entity is created, the previously used id will point to the new version, despite being similar.
Only when explicitly requesting a version, using the version relation scope), is the id guaranteed to point to that specific version.
All request and response bodies are represented as JSON objects except for the /contents endpoints.
These endpoints contain an entity’s contents in the request and response bodies.
When making a request to the API which has a body, please note that the Content-Type header must be specified (e.g. Content-Type: application/json).
1.1.1. Pagination
The API supports pagination via the HTTP query parameters offset and limit with integer values.
Although the API itself supports pagination, it is up to the connector to actually implement it: this is clearly listed in each connector feature list as pagination.
If a connector does not support pagination or the request does not include pagination fields, then the result set is returned as a whole without pagination.
When pagination is specified, the result set is returned to the requestor by first skipping offset records and then taking the following limit records.
An offset of 0 will not skip any record.
A limit of 1 will return 1 record.
If at any time while applying the offset the result set is exhausted (the end is reached) then an empty result will be returned.
If at any time applying the limit the result set is exhausted (the end is reached) then the records collected so far are returned.
GET https://xillio.xill.io/v2/entities/59e4b5a6857/aba0005a28227?offset=2&limit=7offset and limit for the Nth page of M elementsIf every page contains M elements, then the Nth page starts at the element ordinal (N - 1) * M + 1. For example, the first page starts at (1 - 1) * M + 1 = 1, so the offset is 0 (no elements to skip).
The second page starts at ordinal M + 1, so the offset is M.
The number of elements to skip is therefore one less than the ordinal of the first element on the given page.
The size of the page is straightforward, since it is given by the M parameter, thus yielding:
offset = (N - 1) * M
limit = M1.2. Authorization and Authentication
The Xillio API uses OAuth2 with the password flow for authentication.
To use the API it is generally required to have a valid OAuth2 token as an Authorization header with a Bearer access token, and a sufficient level of privilege for the corresponding user.
The authorization logic relies on the OAuth2 scopes mechanics, as documented here.
Getting a token requires a username and password.
Using this authentication method requires to specify client_id=app.
Don’t forget to add this to each requests like shown below.
|
1.2.1. Retrieve a JWT token
Get a JWT token in exchange for a client id, client secret, username and password.
POST /oauth/token ------ HTTP/1.1 200 OK
$ curl 'https://demo-tenant.xill.io/oauth/token' -i -X POST \
-H 'Content-Type: application/x-www-form-urlencoded;charset=ISO-8859-1' \
-d 'grant_type=password&client_id=app&username=demo-user&password=demo-password'| Path | Type | Description |
|---|---|---|
|
|
The bearer token to provide on subsequent API calls. |
|
|
The type of the JWT token. |
|
|
The number of seconds before this token expires. |
|
|
Space-separated list of scopes for this token. |
|
|
Identifier of this token. |
|
|
Name of the tenant, for which this token is authorized. |
HTTP/1.1 200 OK
{
"access_token" : "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOlsieGlsbGlvX2FwaSJdLCJ1c2VyX25hbWUiOiJkZW1vLXVzZXIiLCJzY29wZSI6WyJ1c2VyIiwidXNlcnMiLCJjb25maWd1cmF0aW9ucyIsImNvbnRlbnRzY3JpcHRzIiwicXVlcnk6Y29uZmlndXJlIiwicXVlcnk6ZXhlY3V0ZSIsInR5cGVzIiwidGVtcGxhdGVzIiwiZW50aXRpZXMiLCJjb250ZW50cyIsInRlbmFudCIsInJwYyIsInNlYXJjaCJdLCJleHAiOjE3MTA0NDczOTQsImF1dGhvcml0aWVzIjpbIlJPTEVfQ09ORklHX0FETUlOIiwiUk9MRV9SUENfVVNFUiIsIlJPTEVfVVNFUl9BRE1JTiIsIlJPTEVfQ09OVEVOVFNDUklQVF9BRE1JTiIsIlJPTEVfU0VBUkNIIiwiUk9MRV9FTlRJVFlfQURNSU4iLCJST0xFX0VOVElUWV9VU0VSIiwiUk9MRV9RVUVSWV9BRE1JTiJdLCJqdGkiOiJkMDFkMDE1Yy01OWM3LTQ2NTUtYjQ5ZC1jZDM5YjgzODYzMmEiLCJ0ZW5hbnQiOiJkZW1vLXRlbmFudCIsImNsaWVudF9pZCI6ImFwcCJ9.mPXLIGbj_xdcUksUF1yASX0vUtcYUjWbrM4KfKY9Cxk",
"token_type" : "bearer",
"expires_in" : 43199,
"scope" : "user users configurations contentscripts query:configure query:execute types templates entities contents tenant rpc search",
"tenant" : "demo-tenant",
"jti" : "d01d015c-59c7-4655-b49d-cd39b838632a"
}
Nearly all endpoints require an Authorization header with a Bearer access token.
See the relevant endpoint documentation for details about the necessary OAuth2 scopes for your user.
|
1.2.2. Authorization Scopes and Roles
The access_token must be provided in other API calls as a Bearer token in the Authorization header.
Such headers are commonly omitted in code snippets for brevity, but endpoints do list their requirements in term of OAuth2 user scopes.
Tokens granted in exchange for a user/password combination are valid for a list of "scopes". This is an overview of possible scopes:
| Scope name | Description |
|---|---|
|
Allows access to the /entities endpoint. |
|
Allows access to the /contents endpoint. |
|
Allows access to the /types endpoint. |
|
Allows access to the /templates endpoint. |
|
Allows access to the /tenant endpoint. |
|
Allows access to the /configurations endpoint. |
|
Allows access to the /configurations/contentScripts endpoint. |
|
Allows access to the /configurations/queries configuration endpoint. |
|
Allows access to the /queries endpoint. |
|
Allows access to the /users endpoint. |
|
Allows access to the /user endpoint. |
|
Allows access to the /rpc endpoint. |
|
Allows access to the /search endpoint. |
These scopes give access to specific endpoints. Users have limited permissions on those endpoints, which is expressed using roles:
| Role | Description |
|---|---|
|
Allows administration of users. |
|
Allows administration of configurations. |
|
Allows administration of content scripts. |
|
Allows administration of named query configurations. |
|
Allows modification, deletion and write access to content stored in repositories. |
|
Allows read access to content stored in repositories. |
1.2.3. Passthrough Authorization
Normally a configuration for a repository will contain enough information to authenticate to the target repository transparently from the API user.
When that is not possible, advisable or the target repository uses an unsupported authentication protocol, you can create a configuration using the passthroughAuthorization option set to true.
The Passthrough-Authorization header is then required when making requests using that configuration.
Failure to provide the header results in an Authorization Failed error.
Two types of Passthrough-Authorization are supported: Basic and Bearer.
When you specify the Basic authentication header the username and password fields from your configuration are overridden.
When you specify the Bearer authentication header the token field is overridden.
| This should not be confused with the authentication required to access the Xillio API: passthrough authorization deals with authenticating towards the target repository. |
1.3. Entities
The Xillio API format describes entities from many different content repositories, and allows to deal with content without in-depth knowledge of the underlying content repository.
Entities are designed to be declarative.
This means that entities can be created or updated without having to know anything about the operations required to change their state in the target system.
For example, to update an entity: retrieve it using the get entity endpoint, adjust the modified decorators where necessary, and post it to the update entity endpoint.
Entities are always represented in JSON, and contain several fields:
| Field | Type | Description |
|---|---|---|
|
|
A URL that points to the entity. |
|
|
A URL that is used internally to point to the entity. This value can be found in error messages and entity results. |
|
|
A simple content type string that describes the best match for the entity. |
|
|
An object containing all decorators as they were found in the content repository. This field is used by the create entity endpoint. |
|
|
An object containing all decorators as they will be represented in the content repository.
This field is identical to |
{
"entity" : {
"id" : "https://xillio.xill.io/v2/entities/59e4b5a6857aba0005a28227",
"xdip" : "xdip://59e4b5a6857aba0005a28227/",
"kind" : "Folder",
"original" : {
"container" : {
"hasChildren" : true
},
"created" : {
"date" : "2017-08-22T14:24:50.000Z"
},
"modified" : {
"date" : "2017-08-22T14:24:50.000Z"
},
"name" : {
"systemName" : "root",
"displayName" : "root"
},
"fileSystem" : {
"path" : "/"
}
},
"modified" : {
"container" : {
"hasChildren" : true
},
"created" : {
"date" : "2017-08-22T14:24:50.000Z"
},
"modified" : {
"date" : "2017-08-22T14:24:50.000Z"
},
"name" : {
"systemName" : "root",
"displayName" : "root"
},
"fileSystem" : {
"path" : "/"
}
}
}
}1.3.1. Decorators
Within an entity, the 'original' and 'modified' sections contain decorators. Decorators are named sets of closely related fields. A collection of decorators is provided to represent most common metadata fields. Fields must be of one of the following types:
| Type | Description |
|---|---|
|
Either |
|
An integer or decimal number. |
|
A textual value. A blank string value means: "intentionally left blank". |
|
A URL formatted string value. |
|
An ISO date formatted string value. Format: |
|
A |
|
A nested object containing key-value pairs. |
For each field an indicator is given whether the field is required or optional. Required fields cannot be omitted and cannot have value 'null'. Optional fields can be set to null or may be omitted entirely.
Container
The container decorator signifies an entity that can have children.
If the decorator is not present on an entity, the entity cannot have children.
For example, this decorator is not present on an entity representing a file in a file system.
When the container decorator is present, the entity can have children.
For example, this decorator is present on an entity representing a folder in a file system.
{
"container": {
"hasChildren": true
}
}| Field Name | Description | Type | Required |
|---|---|---|---|
|
Set to |
ContentType
The contentType decorator contains the content type used by the target system. The exact value differs for every
connector.
{
"contentType": {
"systemName": "86797349759843867824",
"displayName": "FileMetadata"
}
}| Field Name | Description | Type | Required |
|---|---|---|---|
|
The human readable name of the content type. |
||
|
Deprecated (see notes). The name of the content type. |
||
|
The technical name of the content type. Can also be a system specific unique id or name. |
Notes
The use of contentType.name has been deprecated. This field has been changed to contentType.systemName in order to distinguish
a system-specific technical name of a content type from a human readable one.
Some systems might not have a human readable content type name. In that case the contentType.displayName field should be equal to the
contentType.systemName field.
Created
The created decorator signifies when an entity was created.
{
"created": {
"date": "2017-08-22T14:29:53.000+02:00",
"by": {
"systemName": "5508584",
"displayName": "Ernst van Rheenen",
"email": "ernst.rheenen@example.com"
}
}
}| Field Name | Description | Type | Required |
|---|---|---|---|
|
The creation date of the entity. Has millisecond accuracy. The time zone is formatted as |
||
|
An object specifying the user that created this entity. |
| Field Name | Description | Type | Required |
|---|---|---|---|
|
The technical name of the user. Can also be a system specific unique id or name. |
||
|
The human readable name of the user. |
||
|
The email address associated with the user. |
Description
The description decorator provides a small excerpt or description for an entity. This is generally used as a preview
message or subtitle.
{
"description": {
"short": "Code because you can!"
}
}| Field Name | Description | Type | Required |
|---|---|---|---|
|
A short extract or subtitle of the entity. |
File
The file decorator contains various pieces of information related to files on a file system.
{
"file": {
"extension": "jpg",
"rawExtension": "JPG",
"size": 12697
}
}| Field Name | Description | Type | Required |
|---|---|---|---|
|
The (optionally cleaned) extension of the file. Not present when the file does not have an extension. |
||
|
The extension of the file as found on the filesystem. Contains the empty string ( |
||
|
The size of the file in bytes. |
Notes
The extension field is automatically computed from an internal extension database. It contains a normalized
version of the rawExtension field. For instance, if the rawExtension field contains PNG, the extension field
contains png.
FileSystem
The fileSystem decorator contains the absolute path of a file or folder on the configured repository.
{
"fileSystem": {
"path": "/home/dave/Pictures"
}
}| Field Name | Description | Type | Required |
|---|---|---|---|
|
The absolute path of the folder from the 'root' of the configured repository. |
Hash
The hash decorator contains one or more types of hashes corresponding to the entity.
{
"hash": {
"md5": "75f12bf60fd789722416e8feec3f4e83",
"sha1": "de60ab502c20cd0cfb18c80f823e6d1dac94aa7a",
"sha256": "3b9deece7e58947079d8a73d88ad0694e296b40d507a7ff9c25f4a4eb1974ec2"
}
}| Field Name | Description | Type | Required |
|---|---|---|---|
|
The |
||
|
The |
||
|
The |
Language
The language decorator contains information about the language of the entity’s content and (optionally) the base entity of which this is a translation.
Whenever a language tag is mentioned, we refer to strings compliant with BCP-47.
{
"tag": "it-IT",
"translationOf": "https://demo-tenant.xill.io/v2/entities/5a27e7d82ab79c00076a78bd/document.txt?language=0"
}| Field Name | Description | Type | Required |
|---|---|---|---|
|
The language tag for this entity. |
||
|
A reference to the entity that is the master from which this one was translated. |
Notes
System specific language tags are converted into BCP-47 compliant tags. Custom language tags defined in target systems are required to be BCP-47 compliant.
MimeType
The mimeType decorator contains a reference to the type of media that is contained by the entity.
A list of types can be found on http://www.freeformatter.com/mime-types-list.html.
{
"mimeType": {
"type": "text/plain"
}
}| Field Name | Description | Type | Required |
|---|---|---|---|
|
The MIME Type of the entity’s contents. |
Modified
The modified decorator signifies when an entity was last modified.
{
"modified": {
"date": "2017-08-22T14:29:53.000+02:00",
"by": {
"systemName": "13",
"displayName": "Thomas Biesaart",
"email": "thomas.biesaart@example.com"
}
}
}| Field Name | Description | Type | Required |
|---|---|---|---|
|
The last modification date of the entity. Has millisecond accuracy. The time zone is formatted as |
||
|
An object specifying the user that last modified this entity. |
| Field Name | Description | Type | Required |
|---|---|---|---|
|
The technical name of the user. Can also be a system specific unique id or name. |
||
|
The human readable name of the user. |
||
|
The email address associated with the user. |
Name
The name decorator represents both a technical name and a human readable name for an entity. This could be anything from
the title of a web page to the filename of a document.
{
"name": {
"displayName": "Three Basic Personas",
"systemName": "personas.docx"
}
}| Field Name | Description | Type | Required |
|---|---|---|---|
|
The human readable name of the entity. |
||
|
The technical name of the entity. Can also be a system specific unique id or name. |
Notes
Some systems might not have a human readable name. In that case the name.displayName field should be equal to the
name.systemName field.
Parent
The parent decorator contains a reference to the entity’s parent.
{
"parent": {
"id": "https://demo-tenant.xill.io/v2/entities/59e4b5a6857aba0005a28228/images/2017"
}
}| Field Name | Description | Type | Required |
|---|---|---|---|
|
The URL that points to the entity’s parent. |
Update
An entity can be moved in the path relation scope by changing the parent decorator in an update entity call. Afterwards the entity will be contained in the entity specified in the modified parent decorator and removed from its original container.
| If the parent decorator is set to a non-existing entity the update will return a No Such Entity error. |
| If the parent decorator is set to an entity that cannot contain other entities update will return an Operation Not Allowed error. |
Preview
The preview decorator provides a location for previews of an entity that the underlying system provides.
For instance, if the entity is a piece of source code from GitHub, the preview.html field contains a URL to the GitHub view of that code.
This can also be a system specific URL to a resource.
{
"preview": {
"html": "https://github.com/ChappIO/loud/blob/master/README.md"
}
}| Field Name | Description | Type | Required |
|---|---|---|---|
|
A web view that can be opened in a browser. |
Notes
Note that the URL must not point to the Xillio API contents endpoint for this entity.
Version
The version decorator contains the version number of the entity.
{
"version": {
"tag": "36354-436"
}
}| Field Name | Description | Type | Required |
|---|---|---|---|
|
The version number or tag of this entity. |
Notes
This decorator is read-only. It cannot be used to update the version of an entity.
Workflow
The workflow decorator signifies the state of the entity in the workflow of the target system.
{
"workflow": {
"status": {
"systemName": "5508585",
"displayName": "publish",
"normalized": "PUBLISHED"
},
"date": "2017-08-22T14:29:53.000+02:00",
"by": {
"systemName": "5508584",
"displayName": "Ernst van Rheenen",
"email": "ernst.rheenen@example.com"
}
}
}| Field Name | Description | Type | Required |
|---|---|---|---|
|
An object specifying the status within the workflow for this entity. |
||
|
The date at which this status is set.
Has millisecond accuracy.
The time zone is formatted as |
||
|
An object specifying the user that set this status. |
| Field Name | Description | Type | Required |
|---|---|---|---|
|
The technical name of the user. Can also be a system specific unique id or name. |
||
|
The human readable name of the user. |
||
|
The email address associated with the user. |
| Field Name | Description | Type | Required |
|---|---|---|---|
|
The technical name of the status. Can also be a system specific unique id or name. Should always be present when reading entities if the workflow decorator is present. |
||
|
The human readable name of the status. |
||
|
The normalized interpretation of the status to provide unification among target systems. Any of: "DRAFT", "PUBLISHED", "ARCHIVED". |
For read operations entities always provide at least status.systemName
For write operations with workflow decorator:
-
If not present, the connectors will default to target system’s least impactful status. For example, in web content management systems, an entity would rather be created in draft state than published.
-
If present, either
status.systemNameorstatus.normalizedStatusmust always be filled, however thestatus.normalizedStatustakes precedence if filled. If neither is filled or if the system is not able to work with either field, an error will be thrown.
The number of normalized statuses is likely to grow in the future as more unification possibilities have been identified amongst systems.
1.4. Downloading Files
The Xillio API allows to download files that are stored in any content repository. Files can be downloaded from a configured content repository using the /contents endpoint. For example:
$ curl 'https://demo-tenant.xill.io/v2/contents/59e0b361a7b11b000586ebea/images/logo.png' --output logo.pngDownloading a file is only possible if the target entity contains contents. If the target entity is not capable of containing contents, the response will be a No Binary Content error.
When updating or downloading an entity’s contents, it is necessary to supply respectively a Content-Type or Accept header.
The values from these headers are used to determine which content script should be run to transform the content.
If these headers are not specified they will default to application/octet-stream, which indicates that the content should remain unchanged.
See the Content Scripts section for more information on how to write such a script.
1.5. Updating Entities
The Xillio API allows to retrieve and update entities in configured content repositories. For example:
let request = require('request');
const baseUrl = 'https://demo-tenant.xill.io/v2';
// Get the entity
request({
url: baseUrl + '/entities/59faf4f2a7b11b0005a8c264/SANDBOX.md',
json: true
}, function(error, response, body) {
// Update the name
body.entity.modified.name.systemName = "RENAMED.md";
// Send it back
request({
method: 'put',
url: body.entity.id,
json: body.entity
}, function(error, response, body) {
console.log("Updated Name: ", body.entity.original.name.displayName);
});
});1.6. Scopes for Entities
When the target of a request to the Xillio API is an entity or a collection of entities, it is possible to use the scopes for entities as an expressive way to retrieve different aspects of an entity, such as additional metadata or other related entities.
All /entities endpoints support scopes, except for the DELETE requests.
To specify a scope for a request, add a scope query parameter with a comma-separated list of scope names.
The response json will contain an element for each requested scope.
Using a scope that does not exist will raise a No Such Scope error.
There are two broad categories of scopes: those that retrieve a different representation for an entity (return type scope), and those that retrieve other entities in relation with an entity (relation scope).
It is not always required to specify a scope.
The default one is the entity return type.
|
1.6.1. Return Type Scopes
These scopes provide a way to extract different kinds of information from an entity. They can be used alone, or as the last part of a relation scope.
| Value | Description |
|---|---|
|
All entity metadata that is mapped to the Xillio API standard entity format. |
|
All metadata that is not mapped to the Xillio API standard entity format. See the section User-defined Metadata |
1.6.2. Relation Scopes
Relation scopes allow retrieving entities related to the entity that is the subject of the current request.
It consists of three parts separated by underscores (_):
-
the relation type,
-
the direction,
-
the return type.
The combination of those three components represent a valid scope, although the availability of a specific scope is connector dependent, and specified in every "Feature and limitations" sections.
Relation type
The relation type denotes the type of related information to retrieve, or in other words, the relation to navigate. Currently, the following are defined:
| Value | Description |
|---|---|
|
Containment relation as in file systems and the internet. |
|
Relation between realizations of the same entity at different times. |
|
Relation between different translations of the same entity, i.e. same content, different language. This applies to both content and metadata. |
Direction
The direction of the scope represents the kind of navigation strategy to be performed on the relation. In general, relations give rise to trees or graphs, in some cases we view the relation simply as a set (a complete, undirected graph).
| Value | Description |
|---|---|
|
The direct ancestors, i.e. the first level of entities reachable by ascending (going against) the relation arrows |
|
The direct descendants, i.e. the first level of entities reachable by descending (going along) the relation arrows |
|
All entities recursively reachable following all arrows in both directions, including the target. For set-like relations, this is the same as getting any other direction plus the target. If requested from an entity in a tree-like relationship, this will retrieve the whole tree. |
path relation:For instance, if the entity "myFolder" contains the entity "myFile", then the path relation can be navigated:
-
in the
childrendirection from "myFolder", yielding "myfile", -
in the
parentsdirection from "myFile", yielding "myFolder".
translation relation:If the entity "document.EN", written in English, has translations "document.IT" and "document.DE" for Italian and German.
By requesting the all direction targeting any of the mentioned entities it is possible to retrieve the list of all translations, obtaining in every case "document.EN", "document.IT", "document.DE".
If the parents direction from "document.IT" is requested, the result depends on the target repository support for translations:
-
if it has a concept of a "source" document, reflected in the
translationOffield of thelanguagedecorator, then only the original document is returned (in this case "document.EN"). -
if however the target repository does not have such support thus representing the translation relation as a set, all translations are returned, with the exception of the target of the request (the result will be "document.DE" and "document.EN").
Return type
The return type determines the format of the data returned by a relationship scoped request, much in a similar way to the case of a return type scoped request, but applied to all entities reached by the navigation strategy.
| Value | Description |
|---|---|
|
All entity metadata that is mapped to the Xillio API standard entity format |
|
The URL (id) of the entities |
Examples
GET /v2/entities/{configurationId}/{path}?scope=entity,path_children_entity{
"entity" : { ... },
"path_children_entity" : [
{ ... },
{ ... },
...
]
}GET /v2/entities/{configurationId}/{path}?scope=version_all_reference,translation_all_reference{
"version_all_reference" : [
{"id" : "<version1-url>", "versionTag" : "1"},
{"id" : "<version2-url>", "versionTag" : "2"},
....
],
"translation_all_reference" : [
{"id" : "<translation-Italian-url>", "languageTag" : "IT_it"},
{"id" : "<translation-French-url>", "languageTag" : "FR_fr"},
....
]
}GET /v2/entities/{configurationId}/{path}?scope=version_parents_entity{
"version_parents_entity" : [
{ ... },
{ ... }
]
}| See Entities for more detailed examples. |
1.6.3. Legacy Scopes
For backward compatibility, "legacy" scopes are still usable. Their use is deprecated and should be replaced by the new scope system whenever possible. Their description here is provided as an aid for code migration.
Those scopes consist of a single value, and cannot be combined.
| Value | Equivalent | Description |
|---|---|---|
|
|
The list of references to the children of the entity |
|
|
The children of the entity |
|
|
The list of references to the translations of the entity |
|
|
The translations of the entity |
|
|
The list or references to the versions of the entity |
|
|
The versions of the entity |
1.6.4. Scopes for the Entity Endpoint
As a reference, this section presents a summary of the rules governing the use of the scopes, as well as an exhaustive list of all the available scopes with their semantics.
General Scope Rules
-
The default scope is always
entity -
Any number of scopes can be specified for a request, as a comma-separated list
-
Scopes which do not apply to an endpoint as specified by its documentation will raise an exception in the HTTP 400 range
-
Scopes which are not natively available on the target repository or not supported by a connector will result in an empty list in the response (
[]) -
For each requested scope, the response will contain an element named after the scope name.
-
Duplicate scopes will be ignored
Scope List
In this list, "the subject" refers to the entity to which the scope will be applied, for example the entity referred by the URL used to issue the request.
The * in the scope denotes the part that has to be completed with one of the scope return types, and which will format the elements of the response as URLs or as JSON structures following the Xillio API standard entity format.
| Scope | Description | Comments |
|---|---|---|
|
All metadata mapped to the standard Xillio API format |
See Entities for more information |
|
All metadata not mapped to the standard Xillio API format |
See User-defined Metadata for more information |
|
All entities containing the subject |
In most cases, returns a list containing the parent folder(s) |
|
All entities contained in the subject |
|
|
All entities reachable from the subject with any number of steps along the path containment relation |
In a simple file system, returns all files and folders |
|
The entity from which the subject was translated |
One document only is expected as result for repositories that have a master document concept for translations, while most systems will return all translations for the target instead |
|
The entities which are translations of the subject |
The direct translations of the target are expected as result for repositories that have a master document concept for translations, while most systems will instead return all translations for the target, direct or not |
|
All translations for the subject |
|
|
The predecessors of the subject |
In most cases, returns the previous version. See the Notes on versions |
|
The entities derived from the subject |
In most cases, returns the next version. See the Notes on versions |
|
All versions of the subject |
Returns the whole version history for the target, including next versions |
Notes on versions
In most repositories the version history is linear, i.e. every document has at most one previous version and at most one next version.
As with translation, some repositories do not record the previous version as such, but rely on the version tag to infer their sequence.
In this case, when asking for any version scope, the behaviour is connector-specific.
1.6.5. User-defined Metadata
The metadata scope allows to retrieve all user-defined metadata of an entity. This returns all properties from the target system in a unified structure. Most properties are grouped in templates, but some properties are part of the content type definition. Templates are reusable groups of strongly related properties that can be applied to an entity.
| Property | Example | Description |
|---|---|---|
|
|
The unique identifier for the content type. |
|
|
The human-readable name for the content type. |
|
|
The description for the content type. |
|
|
The value of this property. This can be a string, number, boolean or a list of strings. |
|
|
The human-readable name for the template. |
|
|
The description for the template. |
|
|
The value of this property. This can be a string, number, boolean or a list of strings. |
{
"contentType": {
"systemName": "c6f334cc708c",
"properties": {
"size": {
"displayName": "File Size",
"description": "The size in bytes.",
"value": 9786
}
}
},
"templates": {
"ca266bbfea62": {
"displayName": "Offshore Project",
"description": "A project executed by an external partner.",
"properties": {
"partner": {
"displayName": "Executing Partner",
"value": "Acme Inc."
},
"customer": {
"displayName": "Customer",
"value": "L. Cartoons Ltd."
},
"status": {
"displayName": "Project Status",
"description": "Planned, in progress, canceled, finished.",
"value": "in progress"
}
}
}
}
}1.7. Content Scripts
Content scripts are Node.js scripts that export a transformation function.
This function should return the mapped content: this can be a string, an object or a Buffer.
When the script is used this function will be invoked with an object containing the unmapped content.
If the passEntity flag is set to true on the content script, the input will also contain the entity object.
| Property | Description |
|---|---|
content |
A |
entity |
An optional JSON object containing the entity. |
The simplest content script is one that directly returns the content: the identity script.
module.exports = function(input) {
return input.content;
};Any errors that occur in the script are directly translated to errors on the API.
| Content scripts have a runtime limit of 10 seconds. If a script runs for too long it will be aborted and an error will be returned. |
1.8. Named Queries
Named queries (aka query configurations) are string templates written for a specific repository’s query language and identified by a unique name in the repository configuration.
The query templates have to be written for a target system that supports querying.
They use the ${…} syntax for their variables, and the variable names have to be prefixed by q_.
Suppose the target repository accepts this type of queries:
https://www.xill.io/content/search?type=pdf
then the corresponding named query configuration will be:
{
"name": "type_query"
"template": "type=${q_type}"
}
and calling /queries endpoint will be done with the following parameters:
/type_query?q_type=pdf
| Malformed, missing or superfluous template variables will cause errors when calling the endpoints. |
2. API Endpoints
Here is an exhaustive list of all the endpoints provided by the API.
2.1. /entities
2.1.1. List Available Repositories
List all available repositories as entities.
When requesting the root entity (/entities) with the scope path_children_entity, all available repositories will be returned.
The configurationId of each configuration can be found in the name.systemName decorator field,
and this can be used in other calls to the API where a configurationId is required.
This endpoint requires an access_token for scope entities for a user with role ENTITY_USER.
|
GET /v2/entities?scope=path_children_entity ------ HTTP/1.1 200 OK Content-Type: application/json
| Parameter | Description |
|---|---|
|
A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included. |
|
A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored. |
|
A comma-separated list of scopes. The available scopes are |
$ curl 'https://demo-tenant.xill.io/v2/entities?scope=path_children_entity' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'The response fields depend on the requested scopes.
HTTP/1.1 200 OK
{
"path_children_entity" : [ {
"id" : "https://demo-tenant.xill.io/v2/entities/aff14503c790482fbbf3ea9302301c4f",
"xdip" : "xdip://aff14503c790482fbbf3ea9302301c4f/",
"kind" : "FileSystem",
"original" : {
"container" : {
"hasChildren" : true
},
"name" : {
"systemName" : "aff14503c790482fbbf3ea9302301c4f",
"displayName" : "My filesystem configuration"
}
},
"modified" : {
"container" : {
"hasChildren" : true
},
"name" : {
"systemName" : "aff14503c790482fbbf3ea9302301c4f",
"displayName" : "My filesystem configuration"
}
}
} ]
}2.1.2. Get an Entity or its Relations
Get a set of decorators containing metadata about the requested entity and, based on the given scopes, about related entities, such as its contained documents, its versions or translations.
The default scope is entity.
Passthrough Authorization
This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.
This endpoint requires an access_token for scope entities for a user with role ENTITY_USER.
|
GET /v2/entities/{configurationId}/{path}
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The XDIP path to the entity. |
| Parameter | Description |
|---|---|
|
A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included. |
|
A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored. |
|
A comma-separated list of scopes. The available scopes are |
$ curl 'https://demo-tenant.xill.io/v2/entities/882f419bf8a9449684c4e48220c6ca34/Documents?scope=entity&include=name,file' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'The response fields depend on the requested scopes.
HTTP/1.1 200 OK
{
"entity" : {
"id" : "https://demo-tenant.xill.io/v2/entities/882f419bf8a9449684c4e48220c6ca34/Documents",
"xdip" : "xdip://882f419bf8a9449684c4e48220c6ca34/Documents",
"kind" : "Folder",
"original" : {
"name" : {
"systemName" : "Documents",
"displayName" : "Documents"
}
},
"modified" : {
"name" : {
"systemName" : "Documents",
"displayName" : "Documents"
}
}
}
}2.1.3. Get the Metadata of an Entity
Get the user-defined metadata from the target system. These are metadata fields which are created by a user or application to enhance content.
Passthrough Authorization
This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.
This endpoint requires an access_token for scope entities for a user with role ENTITY_USER.
|
GET /v2/entities/{configurationId}/{path}?scope=metadata
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The XDIP path to the entity. |
| Parameter | Description |
|---|---|
|
A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included. |
|
A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored. |
|
A comma-separated list of scopes. The available scopes are |
$ curl 'https://demo-tenant.xill.io/v2/entities/0aed53003b404541b670c307182ba138/Documents/Resume.docx?scope=metadata' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'The response fields depend on the requested scopes.
HTTP/1.1 200 OK
{
"metadata" : {
"contentType" : {
"displayName" : "FileData",
"systemName" : "FileData",
"properties" : {
"lastAccessTime" : {
"value" : "2024-03-14T08:17:00.343879Z"
},
"lastModifiedTime" : {
"value" : "2024-03-14T08:17:00.343879Z"
},
"size" : {
"value" : "360"
},
"creationTime" : {
"value" : "2024-03-14T08:17:00.343879Z"
},
"isSymbolicLink" : {
"value" : "false"
},
"isRegularFile" : {
"value" : "true"
},
"fileKey" : {
"value" : "(dev=53,ino=2977814)"
},
"isOther" : {
"value" : "false"
},
"isDirectory" : {
"value" : "false"
}
}
},
"templates" : { }
}
}2.1.4. List References to the Contained Documents of an Entity
Get a reference to the documents contained in the requested entity, i.e. the `id`s or URLs of the documents contained in the document referenced by the URL of this request.
| You can set the 'scope' parameter on all requests that return an entity. This is merely an example. |
| It is possible to specify multiple scopes in a single request, allowing you to request all the data you need in a single round trip. |
This endpoint requires an access_token for scope entities for a user with role ENTITY_USER.
|
GET /v2/entities/{configurationId}/{path}?scope=path_children_reference
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The XDIP path to the entity. |
| Parameter | Description |
|---|---|
|
A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included. |
|
A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored. |
|
A comma-separated list of scopes. The available scopes are |
$ curl 'https://demo-tenant.xill.io/v2/entities/3d678b3a5e40459b971aaf80ce4f7fa2/path/to/folder?scope=path_children_reference' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'The response fields depend on the requested scopes.
HTTP/1.1 200 OK
{
"path_children_reference" : [ {
"id" : "https://demo-tenant.xill.io/v2/entities/3d678b3a5e40459b971aaf80ce4f7fa2/path/to/folder/avatar.jpg"
}, {
"id" : "https://demo-tenant.xill.io/v2/entities/3d678b3a5e40459b971aaf80ce4f7fa2/path/to/folder/README.md"
} ]
}2.1.5. List the Documents Contained in an Entity
Get all the entity’s contained documents as full entity objects. Note that this is an expensive operation. Only request this scope if you need the details of the children. If you are just looking for their id instead, use the path_children_reference request scope.
| You can set the 'scope' parameter on all requests that return an entity. This is merely an example. |
| It is possible to specify multiple scopes in a single request, allowing you to request all data you need in a single round trip. |
This endpoint requires an access_token for scope entities for a user with role ENTITY_USER.
|
GET /v2/entities/{configurationId}/{path}?scope=path_children_entity
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The XDIP path to the entity. |
| Parameter | Description |
|---|---|
|
A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included. |
|
A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored. |
|
A comma-separated list of scopes. The available scopes are |
$ curl 'https://demo-tenant.xill.io/v2/entities/a9282bb29c7343d3b1021c0cb2219be1/subdirectory?scope=path_children_entity' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'The response fields depend on the requested scopes.
HTTP/1.1 200 OK
{
"path_children_entity" : [ {
"id" : "https://demo-tenant.xill.io/v2/entities/a9282bb29c7343d3b1021c0cb2219be1/subdirectory/config.json",
"xdip" : "xdip://a9282bb29c7343d3b1021c0cb2219be1/subdirectory/config.json",
"kind" : "File",
"original" : {
"contentType" : {
"systemName" : "FileData",
"name" : "FileData",
"displayName" : "FileData"
},
"created" : {
"date" : "2024-03-14T08:16:59.831Z"
},
"file" : {
"rawExtension" : "json",
"extension" : "json",
"size" : 15
},
"hash" : {
"md5" : "e73e607ac7da9724987cbba6e47d954d",
"sha1" : "e2f1bf02ed9117442a00627e121a4f3393768e3f",
"sha256" : "bf955f306034e20bf403b8df4dce1e90adc7e9ee104312942b2f9fd988df025b"
},
"mimeType" : {
"type" : "application/json"
},
"modified" : {
"date" : "2024-03-14T08:16:59.831Z"
},
"name" : {
"systemName" : "config.json",
"displayName" : "config.json"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/a9282bb29c7343d3b1021c0cb2219be1/subdirectory"
},
"fileSystem" : {
"path" : "/subdirectory/config.json"
}
},
"modified" : {
"contentType" : {
"systemName" : "FileData",
"name" : "FileData",
"displayName" : "FileData"
},
"created" : {
"date" : "2024-03-14T08:16:59.831Z"
},
"file" : {
"rawExtension" : "json",
"extension" : "json",
"size" : 15
},
"hash" : {
"md5" : "e73e607ac7da9724987cbba6e47d954d",
"sha1" : "e2f1bf02ed9117442a00627e121a4f3393768e3f",
"sha256" : "bf955f306034e20bf403b8df4dce1e90adc7e9ee104312942b2f9fd988df025b"
},
"mimeType" : {
"type" : "application/json"
},
"modified" : {
"date" : "2024-03-14T08:16:59.831Z"
},
"name" : {
"systemName" : "config.json",
"displayName" : "config.json"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/a9282bb29c7343d3b1021c0cb2219be1/subdirectory"
},
"fileSystem" : {
"path" : "/subdirectory/config.json"
}
}
}, {
"id" : "https://demo-tenant.xill.io/v2/entities/a9282bb29c7343d3b1021c0cb2219be1/subdirectory/notes.docx",
"xdip" : "xdip://a9282bb29c7343d3b1021c0cb2219be1/subdirectory/notes.docx",
"kind" : "File",
"original" : {
"contentType" : {
"systemName" : "FileData",
"name" : "FileData",
"displayName" : "FileData"
},
"created" : {
"date" : "2024-03-14T08:16:59.831Z"
},
"file" : {
"rawExtension" : "docx",
"extension" : "docx",
"size" : 360
},
"hash" : {
"md5" : "12479eed8c4db56da287a0e790fee4c8",
"sha1" : "c1840749b4a81d99e5164e51cced3ed7bc6c1c97",
"sha256" : "c156c43acda9fc45d22c2508becfcd230a2f8b0376a1eaf6ce2656a68913ddd6"
},
"mimeType" : {
"type" : "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
},
"modified" : {
"date" : "2024-03-14T08:16:59.831Z"
},
"name" : {
"systemName" : "notes.docx",
"displayName" : "notes.docx"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/a9282bb29c7343d3b1021c0cb2219be1/subdirectory"
},
"fileSystem" : {
"path" : "/subdirectory/notes.docx"
}
},
"modified" : {
"contentType" : {
"systemName" : "FileData",
"name" : "FileData",
"displayName" : "FileData"
},
"created" : {
"date" : "2024-03-14T08:16:59.831Z"
},
"file" : {
"rawExtension" : "docx",
"extension" : "docx",
"size" : 360
},
"hash" : {
"md5" : "12479eed8c4db56da287a0e790fee4c8",
"sha1" : "c1840749b4a81d99e5164e51cced3ed7bc6c1c97",
"sha256" : "c156c43acda9fc45d22c2508becfcd230a2f8b0376a1eaf6ce2656a68913ddd6"
},
"mimeType" : {
"type" : "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
},
"modified" : {
"date" : "2024-03-14T08:16:59.831Z"
},
"name" : {
"systemName" : "notes.docx",
"displayName" : "notes.docx"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/a9282bb29c7343d3b1021c0cb2219be1/subdirectory"
},
"fileSystem" : {
"path" : "/subdirectory/notes.docx"
}
}
} ]
}2.1.6. List References to the Translations of an Entity
Get a list of references to the known translations of the requested entity.
| You can set the 'scope' parameter on all requests that return an entity. This is merely an example. |
| It is possible to specify multiple scopes in a single request, allowing you to request all data you need in a single round trip. |
This endpoint requires an access_token for scope entities for a user with role ENTITY_USER.
|
GET /v2/entities/{configurationId}/{path}?scope=translation_all_reference
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The XDIP path to the entity. |
| Parameter | Description |
|---|---|
|
A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included. |
|
A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored. |
|
A comma-separated list of scopes. The available scopes are |
$ curl 'https://demo-tenant.xill.io/v2/entities/fcb149fb018f41ae810407d96b8f393d/biography.pdf?scope=translation_all_reference' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'The response fields depend on the requested scopes.
HTTP/1.1 200 OK
{
"translationList" : [ {
"id" : "https://demo-tenant.xill.io/v2/entities/fcb149fb018f41ae810407d96b8f393d/biography.pdf?language=cs-CZ",
"tag" : "cs-CZ"
}, {
"id" : "https://demo-tenant.xill.io/v2/entities/fcb149fb018f41ae810407d96b8f393d/biography.pdf?language=es-ES",
"tag" : "es-ES"
}, {
"id" : "https://demo-tenant.xill.io/v2/entities/fcb149fb018f41ae810407d96b8f393d/biography.pdf?language=es-MX",
"tag" : "es-MX"
} ]
}2.1.7. Get the Translations of an Entity
Get all of the translations of the entity as full entity objects. Note that this is an expensive operation. Only request this scope if
you need the translation’s details. If you are just looking for their id instead, use the translation_all_reference request scope.
| You can set the 'scope' parameter on all requests that return an entity. This is merely an example. |
| It is possible to specify multiple scopes in a single request, allowing you to request all data you need in a single round trip. |
This endpoint requires an access_token for scope entities for a user with role ENTITY_USER.
|
GET /v2/entities/{configurationId}/{path}?scope=translation_all_entity
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The XDIP path to the entity. |
| Parameter | Description |
|---|---|
|
A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included. |
|
A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored. |
|
A comma-separated list of scopes. The available scopes are |
$ curl 'https://demo-tenant.xill.io/v2/entities/2e13b2883d1e43b6a2ac56f9144a1afa/appointments.docx?scope=translation_all_entity' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'The response fields depend on the requested scopes.
HTTP/1.1 200 OK
{
"translations" : [ {
"id" : "https://demo-tenant.xill.io/v2/entities/2e13b2883d1e43b6a2ac56f9144a1afa/appointments.docx?language=cs-CZ",
"xdip" : "xdip://2e13b2883d1e43b6a2ac56f9144a1afa/appointments.docx?language=cs-CZ",
"kind" : "File",
"original" : {
"container" : {
"hasChildren" : true
},
"file" : {
"rawExtension" : "docx",
"extension" : "docx"
},
"name" : {
"systemName" : "/appointments.docx",
"displayName" : "/appointments.docx"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/2e13b2883d1e43b6a2ac56f9144a1afa?language=cs-CZ"
},
"language" : {
"tag" : "cs-CZ",
"translationOf" : "https://demo-tenant.xill.io/v2/entities/2e13b2883d1e43b6a2ac56f9144a1afa/appointments.docx?language=fr-FR"
}
},
"modified" : {
"container" : {
"hasChildren" : true
},
"file" : {
"rawExtension" : "docx",
"extension" : "docx"
},
"name" : {
"systemName" : "/appointments.docx",
"displayName" : "/appointments.docx"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/2e13b2883d1e43b6a2ac56f9144a1afa?language=cs-CZ"
},
"language" : {
"tag" : "cs-CZ",
"translationOf" : "https://demo-tenant.xill.io/v2/entities/2e13b2883d1e43b6a2ac56f9144a1afa/appointments.docx?language=fr-FR"
}
}
}, {
"id" : "https://demo-tenant.xill.io/v2/entities/2e13b2883d1e43b6a2ac56f9144a1afa/appointments.docx?language=es-ES",
"xdip" : "xdip://2e13b2883d1e43b6a2ac56f9144a1afa/appointments.docx?language=es-ES",
"kind" : "File",
"original" : {
"container" : {
"hasChildren" : true
},
"file" : {
"rawExtension" : "docx",
"extension" : "docx"
},
"name" : {
"systemName" : "/appointments.docx",
"displayName" : "/appointments.docx"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/2e13b2883d1e43b6a2ac56f9144a1afa?language=es-ES"
},
"language" : {
"tag" : "es-ES",
"translationOf" : "https://demo-tenant.xill.io/v2/entities/2e13b2883d1e43b6a2ac56f9144a1afa/appointments.docx?language=fr-FR"
}
},
"modified" : {
"container" : {
"hasChildren" : true
},
"file" : {
"rawExtension" : "docx",
"extension" : "docx"
},
"name" : {
"systemName" : "/appointments.docx",
"displayName" : "/appointments.docx"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/2e13b2883d1e43b6a2ac56f9144a1afa?language=es-ES"
},
"language" : {
"tag" : "es-ES",
"translationOf" : "https://demo-tenant.xill.io/v2/entities/2e13b2883d1e43b6a2ac56f9144a1afa/appointments.docx?language=fr-FR"
}
}
}, {
"id" : "https://demo-tenant.xill.io/v2/entities/2e13b2883d1e43b6a2ac56f9144a1afa/appointments.docx?language=es-MX",
"xdip" : "xdip://2e13b2883d1e43b6a2ac56f9144a1afa/appointments.docx?language=es-MX",
"kind" : "File",
"original" : {
"container" : {
"hasChildren" : true
},
"file" : {
"rawExtension" : "docx",
"extension" : "docx"
},
"name" : {
"systemName" : "/appointments.docx",
"displayName" : "/appointments.docx"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/2e13b2883d1e43b6a2ac56f9144a1afa?language=es-MX"
},
"language" : {
"tag" : "es-MX",
"translationOf" : "https://demo-tenant.xill.io/v2/entities/2e13b2883d1e43b6a2ac56f9144a1afa/appointments.docx?language=fr-FR"
}
},
"modified" : {
"container" : {
"hasChildren" : true
},
"file" : {
"rawExtension" : "docx",
"extension" : "docx"
},
"name" : {
"systemName" : "/appointments.docx",
"displayName" : "/appointments.docx"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/2e13b2883d1e43b6a2ac56f9144a1afa?language=es-MX"
},
"language" : {
"tag" : "es-MX",
"translationOf" : "https://demo-tenant.xill.io/v2/entities/2e13b2883d1e43b6a2ac56f9144a1afa/appointments.docx?language=fr-FR"
}
}
} ]
}2.1.8. List References to All Versions of an Entity
Get a list of references to the known versions of the requested entity.
| You can set the 'scope' parameter on all requests that return an entity. This is merely an example. |
| It is possible to specify multiple scopes in a single request, allowing you to request all data you need in a single round trip. |
This endpoint requires an access_token for scope entities for a user with role ENTITY_USER.
|
GET /v2/entities/{configurationId}/{path}?scope=version_all_reference
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The XDIP path to the entity. |
| Parameter | Description |
|---|---|
|
A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included. |
|
A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored. |
|
A comma-separated list of scopes. The available scopes are |
$ curl 'https://demo-tenant.xill.io/v2/entities/c556c2c1adae493ab041eb96176c7400/biography.pdf?scope=version_all_reference' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'The response fields depend on the requested scopes.
HTTP/1.1 200 OK
{
"versionList" : [ {
"id" : "https://demo-tenant.xill.io/v2/entities/c556c2c1adae493ab041eb96176c7400/biography.pdf?version=1.0",
"tag" : "1.0"
}, {
"id" : "https://demo-tenant.xill.io/v2/entities/c556c2c1adae493ab041eb96176c7400/biography.pdf?version=1.1",
"tag" : "1.1"
}, {
"id" : "https://demo-tenant.xill.io/v2/entities/c556c2c1adae493ab041eb96176c7400/biography.pdf?version=2.0",
"tag" : "2.0"
} ]
}2.1.9. Get the Versions of an Entity
Get all of the entity’s versions as full entity objects. Note that this is an expensive operation. Only request this scope if
you need the version’s details. If you are just looking for their id instead, use the version_all_reference request scope.
| You can set the 'scope' parameter on all requests that return an entity. This is merely an example. |
| It is possible to specify multiple scopes in a single request, allowing you to request all data you need in a single round trip. |
This endpoint requires an access_token for scope entities for a user with role ENTITY_USER.
|
GET /v2/entities/{configurationId}/{path}?scope=version_all_entity
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The XDIP path to the entity. |
| Parameter | Description |
|---|---|
|
A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included. |
|
A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored. |
|
A comma-separated list of scopes. The available scopes are |
$ curl 'https://demo-tenant.xill.io/v2/entities/f3559399d3cd4db0a7c1211730859895/appointments.docx?scope=version_all_entity' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'The response fields depend on the requested scopes.
HTTP/1.1 200 OK
{
"versions" : [ {
"id" : "https://demo-tenant.xill.io/v2/entities/f3559399d3cd4db0a7c1211730859895/appointments.docx?version=1.0",
"xdip" : "xdip://f3559399d3cd4db0a7c1211730859895/appointments.docx?version=1.0",
"kind" : "File",
"original" : {
"container" : {
"hasChildren" : true
},
"file" : {
"rawExtension" : "docx",
"extension" : "docx"
},
"name" : {
"systemName" : "/appointments.docx",
"displayName" : "/appointments.docx"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/f3559399d3cd4db0a7c1211730859895?version=1.0"
},
"version" : {
"tag" : "1.0"
}
},
"modified" : {
"container" : {
"hasChildren" : true
},
"file" : {
"rawExtension" : "docx",
"extension" : "docx"
},
"name" : {
"systemName" : "/appointments.docx",
"displayName" : "/appointments.docx"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/f3559399d3cd4db0a7c1211730859895?version=1.0"
},
"version" : {
"tag" : "1.0"
}
}
}, {
"id" : "https://demo-tenant.xill.io/v2/entities/f3559399d3cd4db0a7c1211730859895/appointments.docx?version=1.1",
"xdip" : "xdip://f3559399d3cd4db0a7c1211730859895/appointments.docx?version=1.1",
"kind" : "File",
"original" : {
"container" : {
"hasChildren" : true
},
"file" : {
"rawExtension" : "docx",
"extension" : "docx"
},
"name" : {
"systemName" : "/appointments.docx",
"displayName" : "/appointments.docx"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/f3559399d3cd4db0a7c1211730859895?version=1.1"
},
"version" : {
"tag" : "1.1"
}
},
"modified" : {
"container" : {
"hasChildren" : true
},
"file" : {
"rawExtension" : "docx",
"extension" : "docx"
},
"name" : {
"systemName" : "/appointments.docx",
"displayName" : "/appointments.docx"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/f3559399d3cd4db0a7c1211730859895?version=1.1"
},
"version" : {
"tag" : "1.1"
}
}
}, {
"id" : "https://demo-tenant.xill.io/v2/entities/f3559399d3cd4db0a7c1211730859895/appointments.docx?version=2.0",
"xdip" : "xdip://f3559399d3cd4db0a7c1211730859895/appointments.docx?version=2.0",
"kind" : "File",
"original" : {
"container" : {
"hasChildren" : true
},
"file" : {
"rawExtension" : "docx",
"extension" : "docx"
},
"name" : {
"systemName" : "/appointments.docx",
"displayName" : "/appointments.docx"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/f3559399d3cd4db0a7c1211730859895?version=2.0"
},
"version" : {
"tag" : "2.0"
}
},
"modified" : {
"container" : {
"hasChildren" : true
},
"file" : {
"rawExtension" : "docx",
"extension" : "docx"
},
"name" : {
"systemName" : "/appointments.docx",
"displayName" : "/appointments.docx"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/f3559399d3cd4db0a7c1211730859895?version=2.0"
},
"version" : {
"tag" : "2.0"
}
}
} ]
}2.1.10. Create a New Entity
Create an entity with the given metadata.
Of this entity, only the original section will be used, the modified section will be ignored.
To create an entity with contents, use the Create a New Entity With Contents endpoint.
The parent path of the new entity is given by the request URL. If this happens to be a configuration path, the parent is assumed to be the "root" in the context of the given configuration and target repository. This is because a Xillio API connector configuration always points to a concrete starting folder that might not be the logical root of the file hierarchy in the target repository. For example, the "object store" for Filenet and the "site" for Sharepoint point to a specific part of the repository which constitute the "root" for all connector operations.
This endpoint can be used to create a translation of an already existing document. This is done by setting the Language decorator to a language that does not already exist for the target entity.
This endpoint can be used to create a new version of an already existing document. This can be done by updating the metadata or content of an entity and setting the Version.
Some systems will implicitly create a new version even if the version decorator is not set, please check the specific connector documentation for details.
|
Passthrough Authorization
This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.
This endpoint requires an access_token for scope entities for a user with role ENTITY_ADMIN.
|
POST /v2/entities/{configurationId}/{path}
------
HTTP/1.1 201 Created
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The XDIP path to the entity. |
| Parameter | Description |
|---|---|
|
A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included. |
|
A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored. |
|
A comma-separated list of scopes. The available scopes are |
$ curl 'https://demo-tenant.xill.io/v2/entities/4f97fd5b4be6409baf7a97bc37be8323/' -i -X POST \
-H 'Authorization: Bearer <<YOUR_TOKEN>>' \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{
"kind" : "File",
"original" : {
"name" : {
"systemName" : "a-new-file.txt",
"displayName" : "a-new-file.txt"
}
},
"modified" : {
"name" : {
"systemName" : "a-new-file.txt",
"displayName" : "a-new-file.txt"
}
}
}'The response fields depend on the requested scopes.
HTTP/1.1 201 Created
{
"entity" : {
"id" : "https://demo-tenant.xill.io/v2/entities/4f97fd5b4be6409baf7a97bc37be8323/a-new-file.txt",
"xdip" : "xdip://4f97fd5b4be6409baf7a97bc37be8323/a-new-file.txt",
"kind" : "File",
"original" : {
"contentType" : {
"systemName" : "FileData",
"name" : "FileData",
"displayName" : "FileData"
},
"created" : {
"date" : "2024-03-14T08:16:58.611Z"
},
"file" : {
"rawExtension" : "txt",
"extension" : "txt",
"size" : 0
},
"hash" : {
"md5" : "d41d8cd98f00b204e9800998ecf8427e",
"sha1" : "da39a3ee5e6b4b0d3255bfef95601890afd80709",
"sha256" : "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"mimeType" : {
"type" : "text/plain"
},
"modified" : {
"date" : "2024-03-14T08:16:58.611Z"
},
"name" : {
"systemName" : "a-new-file.txt",
"displayName" : "a-new-file.txt"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/4f97fd5b4be6409baf7a97bc37be8323"
},
"fileSystem" : {
"path" : "/a-new-file.txt"
}
},
"modified" : {
"contentType" : {
"systemName" : "FileData",
"name" : "FileData",
"displayName" : "FileData"
},
"created" : {
"date" : "2024-03-14T08:16:58.611Z"
},
"file" : {
"rawExtension" : "txt",
"extension" : "txt",
"size" : 0
},
"hash" : {
"md5" : "d41d8cd98f00b204e9800998ecf8427e",
"sha1" : "da39a3ee5e6b4b0d3255bfef95601890afd80709",
"sha256" : "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
},
"mimeType" : {
"type" : "text/plain"
},
"modified" : {
"date" : "2024-03-14T08:16:58.611Z"
},
"name" : {
"systemName" : "a-new-file.txt",
"displayName" : "a-new-file.txt"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/4f97fd5b4be6409baf7a97bc37be8323"
},
"fileSystem" : {
"path" : "/a-new-file.txt"
}
}
}
}2.1.11. Create a New Entity With Contents
Create an entity with the given metadata and contents.
This endpoint requires the request to be sent as multipart/form-data.
The request must at least have an entity part which contains the entity object, this part must be of type application/json.
Of this entity, only the original section will be used, the modified section will be ignored.
A contents part can optionally be supplied, this can either be a stream or a file containing the contents of the entity to be created.
To create an entity without contents, use the Create a New Entity endpoint.
The parent path of the new entity is given by the request URL. If this happens to be a configuration path, the parent is assumed to be the "root" in the context of the given configuration and target repository. This is because a Xillio API connector configuration always points to a concrete starting folder that might not be the logical root of the file hierarchy in the target repository. For example, the "object store" for Filenet and the "site" for Sharepoint point to a specific part of the repository which constitute the "root" for all connector operations.
| This endpoint can also be used to create a translation or version of an existing document. Please see Create a New Entity for further info on creating translations or versions. |
| We support creating files up to 1 gigabyte using this endpoint. To upload larger files see the Update an Entity's Contents endpoint. |
Passthrough Authorization
This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.
This endpoint requires an access_token for scope entities for a user with role ENTITY_ADMIN.
|
POST /v2/entities/{configurationId}/{path}
------
HTTP/1.1 201 Created
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The XDIP path to the entity. |
| Parameter | Description |
|---|---|
|
A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included. |
|
A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored. |
|
A comma-separated list of scopes. The available scopes are |
| Part | Description |
|---|---|
|
The JSON formatted entity. |
|
The contents of the entity. |
$ curl 'https://demo-tenant.xill.io/v2/entities/aa66918a82b643cc87f477c590ca9a2b/' -i -X POST \
-H 'Authorization: Bearer <<YOUR_TOKEN>>' \
-H 'Content-Type: multipart/form-data' \
-F 'entity={
"kind" : "File",
"original" : {
"name" : {
"systemName" : "a-new-file-with-contents.txt",
"displayName" : "a-new-file-with-contents.txt"
}
},
"modified" : {
"name" : {
"systemName" : "a-new-file-with-contents.txt",
"displayName" : "a-new-file-with-contents.txt"
}
}
};type=application/json;charset=UTF-8' \
-F 'contents=This file was newly created!'The response fields depend on the requested scopes.
HTTP/1.1 201 Created
{
"entity" : {
"id" : "https://demo-tenant.xill.io/v2/entities/aa66918a82b643cc87f477c590ca9a2b/a-new-file-with-contents.txt",
"xdip" : "xdip://aa66918a82b643cc87f477c590ca9a2b/a-new-file-with-contents.txt",
"kind" : "File",
"original" : {
"contentType" : {
"systemName" : "FileData",
"name" : "FileData",
"displayName" : "FileData"
},
"created" : {
"date" : "2024-03-14T08:16:58.763Z"
},
"file" : {
"rawExtension" : "txt",
"extension" : "txt",
"size" : 28
},
"hash" : {
"md5" : "56e9ecd7dddd89fb5c18578cd1bc2cfb",
"sha1" : "f916fea892a3429c1d2bb7b694a4f79ddece777f",
"sha256" : "14a0e8191d8f8321e734405571f5c6d80b467e85b24931c866fa0b2680fc8611"
},
"mimeType" : {
"type" : "text/plain"
},
"modified" : {
"date" : "2024-03-14T08:16:58.763Z"
},
"name" : {
"systemName" : "a-new-file-with-contents.txt",
"displayName" : "a-new-file-with-contents.txt"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/aa66918a82b643cc87f477c590ca9a2b"
},
"fileSystem" : {
"path" : "/a-new-file-with-contents.txt"
}
},
"modified" : {
"contentType" : {
"systemName" : "FileData",
"name" : "FileData",
"displayName" : "FileData"
},
"created" : {
"date" : "2024-03-14T08:16:58.763Z"
},
"file" : {
"rawExtension" : "txt",
"extension" : "txt",
"size" : 28
},
"hash" : {
"md5" : "56e9ecd7dddd89fb5c18578cd1bc2cfb",
"sha1" : "f916fea892a3429c1d2bb7b694a4f79ddece777f",
"sha256" : "14a0e8191d8f8321e734405571f5c6d80b467e85b24931c866fa0b2680fc8611"
},
"mimeType" : {
"type" : "text/plain"
},
"modified" : {
"date" : "2024-03-14T08:16:58.763Z"
},
"name" : {
"systemName" : "a-new-file-with-contents.txt",
"displayName" : "a-new-file-with-contents.txt"
},
"parent" : {
"id" : "https://demo-tenant.xill.io/v2/entities/aa66918a82b643cc87f477c590ca9a2b"
},
"fileSystem" : {
"path" : "/a-new-file-with-contents.txt"
}
}
}
}2.1.12. Update an Existing Entity
Update an entity based on the differences between the original and modified sections.
When trying to change unmodifiable information, the change is ignored and not reflected in the target system or response body. The returned entity can be used to validate which updates were executed and which were not.
This behaviour is by design and ensures the greatest consistency between different underlying connectors.
Passthrough Authorization
This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.
This endpoint requires an access_token for scope entities for a user with role ENTITY_ADMIN.
|
PUT /v2/entities/{configurationId}/{path}
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The XDIP path to the entity. |
| Parameter | Description |
|---|---|
|
A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included. |
|
A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored. |
|
A comma-separated list of scopes. The available scopes are |
$ curl 'https://demo-tenant.xill.io/v2/entities/82b21f4c0e1d4053a21c0c3c03f1d6d3/existing-file.xml?include=name' -i -X PUT \
-H 'Authorization: Bearer <<YOUR_TOKEN>>' \
-H 'Content-Type: application/json;charset=UTF-8' \
-d '{
"kind" : "File",
"original" : {
"name" : {
"systemName" : "existing-file.xml",
"displayName" : "existing-file.xml"
}
},
"modified" : {
"name" : {
"systemName" : "updated-entity.xml",
"displayName" : "updated-entity.xml"
}
}
}'The response fields depend on the requested scopes.
HTTP/1.1 200 OK
{
"entity" : {
"id" : "https://demo-tenant.xill.io/v2/entities/82b21f4c0e1d4053a21c0c3c03f1d6d3/updated-entity.xml",
"xdip" : "xdip://82b21f4c0e1d4053a21c0c3c03f1d6d3/updated-entity.xml",
"kind" : "File",
"original" : {
"name" : {
"systemName" : "updated-entity.xml",
"displayName" : "updated-entity.xml"
}
},
"modified" : {
"name" : {
"systemName" : "updated-entity.xml",
"displayName" : "updated-entity.xml"
}
}
}
}2.1.13. Delete an Entity
Delete an entity, its contents, and, if any, its path children. Special rules apply when deleting a version from the middle of the version history: different repositories have different rules, but in general it is possible to delete the last version on all repositories that support versioning.
If the entity does not exist, nothing happens.
Passthrough Authorization
This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.
This endpoint requires an access_token for scope entities for a user with role ENTITY_ADMIN.
|
DELETE /v2/entities/{configurationId}/{path}
------
HTTP/1.1 204 No Content
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The XDIP path to the entity. |
$ curl 'https://demo-tenant.xill.io/v2/entities/54b0a6337f67450d8b375b7a13a4d53e/old-file.txt' -i -X DELETE \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'HTTP/1.1 204 No Content2.2. /search
2.2.1. Search by Content
Search through the target repository by textual content.
This endpoint uses the native search engine of the target repository. As such, the results of the search are dependent on the target repository type.
For instance, on some repository the search will be done on content only, while on another the results will include matches based on metadata.
Passthrough Authorization
This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.
This endpoint requires an access_token for scope search for a user with role ENTITY_USER.
|
POST /v2/search/{configurationId}
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
| Parameter | Description |
|---|---|
|
A comma-separated list of scopes. The available scopes are: |
$ curl 'https://demo-tenant.xill.io/v2/search/56d919906a704dd2924c1eea5de5ff41' -i -X POST \
-H 'Authorization: Bearer <<YOUR_TOKEN>>' \
-H 'Content-Type: application/json' \
-d '{"contents": "Sales Department"}'| Path | Type | Description |
|---|---|---|
|
|
This field contains entities' metadata if the 'scope' contains 'entities'. |
|
|
This field contains an array of references to entities if the 'scope' parameter contains 'entityList'. |
HTTP/1.1 200 OK
{
"entityList" : [ {
"id" : "https://demo-tenant.xill.io/v2/entities/56d919906a704dd2924c1eea5de5ff41/message.xml"
} ]
}2.3. /queries
2.3.1. List Your Named Queries for a Repository
List all your named queries for a specific configuration. To create a named query see Create a named query configuration.
This endpoint requires an access_token for scope entities:query for a user with role ENTITY_USER.
|
GET /v2/queries/{configurationId}
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
$ curl 'https://demo-tenant.xill.io/v2/queries/982e37b4f3124b148512249fb306add2' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'| Path | Type | Description |
|---|---|---|
|
|
An array of all your named queries for this configuration. |
|
|
The name of the query configuration. |
|
|
The template of the query, written for the target system. |
HTTP/1.1 200 OK
[ {
"name" : "my_query",
"template" : "parameter=${q_variable}"
} ]2.3.2. Query Entities
The query must be present in the referenced configuration and all template variables must be supplied as request parameters. Specifying variables that are not used in the template also leads to an error.
| URL parameter names must match the corresponding template variables names exactly and must conform to the standard specified in Named Queries. |
The template variable values input to this endpoint are escaped using a method appropriate to the target system.
Passthrough Authorization
This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.
This endpoint requires an access_token for scope query:execute for a user with role ENTITY_USER.
|
GET /v2/queries/{configurationId}/{queryName}?q_variable=33&scope=entities
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The name of this query configuration. |
| Parameter | Description |
|---|---|
|
A comma-separated list of projection rules. Decorators which match these rules will be included. All other decorators will be excluded. By default, all decorators are included. |
|
A comma-separated list of projection rules. Decorators which match these rules will be excluded. If an include rule is given, the exclude rules are ignored. |
|
A comma-separated list of scopes. The available scopes are: |
|
Query template variable value, for each variable defined in the query template |
$ curl 'https://demo-tenant.xill.io/v2/queries/7a5bbef9818b4ceea19b20262a3d085b/my_query?scope=entities&q_variable=value' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'| Path | Type | Description |
|---|---|---|
|
|
This field contains entities' metadata if the 'scope' contains 'entities'. |
|
|
This field contains an array of references to entities if the 'scope' parameter contains 'entityList'. |
HTTP/1.1 200 OK
{
"entities" : [ ]
}2.4. /contents
2.4.1. Download an Entity's Contents
Get the contents of an entity.
Passthrough Authorization
This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.
This endpoint requires an access_token for scope contents for a user with role ENTITY_USER.
|
GET /v2/contents/{configurationId}/{path}
------
HTTP/1.1 200 OK
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The XDIP path to the entity. |
| Name | Description |
|---|---|
|
Which content script to apply, or |
$ curl 'https://demo-tenant.xill.io/v2/contents/ade57d26761d45f78407857c5670f1c8/note.xml' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>' \
-H 'Accept: application/octet-stream'HTTP/1.1 200 OK
<items>
<item>
<title>Hello World</title>
<text>This is a simple note</text>
</item>
</items>2.4.2. Update an Entity's Contents
Overwrite the contents of the entity with the contents of the request body. When calling this endpoint the version of the entity is incremented.
Currently, we support updating files with up to 10 gigabyte using this endpoint.
Passthrough Authorization
This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.
This endpoint requires an access_token for scope contents for a user with role ENTITY_ADMIN.
|
PUT /v2/contents/{configurationId}/{path}
------
HTTP/1.1 204 No Content
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The XDIP path to the entity. |
| Name | Description |
|---|---|
|
Which content script to apply, or |
$ curl 'https://demo-tenant.xill.io/v2/contents/51cc99c0c19a49df9cb37c4f5c9339d9/manifest.txt' -i -X PUT \
-H 'Authorization: Bearer <<YOUR_TOKEN>>' \
-H 'Content-Type: application/octet-stream' \
-d 'This will be the new content!'HTTP/1.1 204 No Content2.5. /types
2.5.1. List All Content Types
List all known content types of the target repository.
This endpoint requires an access_token for scope types for a user with role ENTITY_USER.
|
GET /v2/types/{configurationId}
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
$ curl 'https://demo-tenant.xill.io/v2/types/b5d285434b29411db62a3314364a3cee' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'| Path | Type | Description |
|---|---|---|
|
|
An array of all content types of the target repository. |
|
|
The URL that points to this content type. |
|
|
The technical name of the content type. |
|
|
The human readable name of the content type. If none is given, systemName is used instead. |
|
|
A small excerpt or description of the content type. |
HTTP/1.1 200 OK
[ {
"systemName" : "FileData",
"displayName" : "File or Folder",
"description" : "A file or folder stored on the file system",
"id" : "https://demo-tenant.xill.io/v2/types/b5d285434b29411db62a3314364a3cee/FileData"
} ]2.6. /templates
2.6.1. List All Templates
List all known metadata templates, also known as mixins, of the target repository.
This endpoint requires an access_token for scope templates for a user with role ENTITY_USER.
|
GET /v2/templates/{configurationId}
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
$ curl 'https://demo-tenant.xill.io/v2/templates/dc8120d3b6e04a46b896810fcb60fe85' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'| Path | Type | Description |
|---|---|---|
|
|
An array of all metadata templates, also known as mixins, of the target repository. |
|
|
The URL that points to this template. |
|
|
The technical name of the template. |
|
|
The human readable name of the template. If none is given, systemName is used instead. |
|
|
A small excerpt or description of the template. |
HTTP/1.1 200 OK
[ {
"systemName" : "employer",
"displayName" : "Employer",
"description" : "A person conducting a business or undertaking",
"id" : "https://demo-tenant.xill.io/v2/templates/dc8120d3b6e04a46b896810fcb60fe85/employer"
}, {
"systemName" : "contact",
"displayName" : "Contact",
"description" : "A person who can offer help in achieving goals",
"id" : "https://demo-tenant.xill.io/v2/templates/dc8120d3b6e04a46b896810fcb60fe85/contact"
}, {
"systemName" : "employee",
"displayName" : "Employee",
"description" : "A contributor of labor and expertise to an endeavor of an employer",
"id" : "https://demo-tenant.xill.io/v2/templates/dc8120d3b6e04a46b896810fcb60fe85/employee"
} ]2.7. /tenant
2.7.1. Get your tenant
Retrieve information about your tenant.
This endpoint requires an access_token for scope tenant for a user with role CONFIG_ADMIN.
|
GET /v2/tenant ------ HTTP/1.1 200 OK Content-Type: application/json
$ curl 'https://demo-tenant.xill.io/v2/tenant/' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'| Path | Type | Description |
|---|---|---|
|
|
The id of this tenant |
|
|
Technical name e.g. for usage in URLs |
|
|
Human-readable name for displaying e.g. in a GUI |
|
|
Free form description of this tenant |
|
|
List of connectors that are enabled for this tenant |
HTTP/1.1 200 OK
{
"id" : "2c9180838e3c08a5018e3c08d9120034",
"name" : "demo-tenant",
"displayName" : "demo-tenant",
"description" : "Free form description of the demo-tenant tenant.",
"availableConnectors" : [ "FileSystem" ]
}2.8. /configurations
2.8.1. List All Your Configurations
List all your configurations.
This endpoint requires an access_token for scope configurations for a user with role CONFIG_ADMIN.
|
GET /v2/configurations ------ HTTP/1.1 200 OK Content-Type: application/json
$ curl 'https://demo-tenant.xill.io/v2/configurations' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'| Path | Type | Description |
|---|---|---|
|
|
An array of all configurations that are accessible to you. |
HTTP/1.1 200 OK
[ {
"id" : "7dbb020cf44d4270bc5da685733c4c47",
"name" : "My filesystem configuration",
"configurationType" : "FileSystem",
"passthroughAuthorization" : false,
"config" : {
"rootPath" : "file:///tmp/ApiDocumentationIT9898110354694331731/"
}
} ]2.8.2. Get a Configuration
Get one of your configurations.
This endpoint requires an access_token for scope configurations for a user with role CONFIG_ADMIN.
|
GET /v2/configurations/{configurationId}
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
$ curl 'https://demo-tenant.xill.io/v2/configurations/6dd7f039ad9e4047b581cda19f38df89' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'| Path | Type | Description |
|---|---|---|
|
|
The id of this configuration. |
|
|
The display name of this configuration. |
|
|
The underlying type of the configuration. |
|
|
The properties which are passed to the connector. |
|
|
Set this to true to enable passthrough authorization (default: false). |
HTTP/1.1 200 OK
{
"id" : "6dd7f039ad9e4047b581cda19f38df89",
"name" : "My filesystem configuration",
"configurationType" : "FileSystem",
"passthroughAuthorization" : false,
"config" : {
"rootPath" : "file:///tmp/ApiDocumentationIT3943600070296191093/"
}
}2.8.3. Create a New Configuration
Create a configuration with the given name, configurationType and config fields and an optional id field.
This returns the created configuration, of which the id can be used in other requests.
If set, the chosen id must be unique, can only contain alphanumerics and dashes, and cannot start nor
end with a dash. Additionally, its length must be between 2 to 255 characters. If the id was not set, it will
be automatically generated.
Some values in config are required, in which case a value must be assigned.
Some can also have a default, which can be overwritten by providing a value for the field.
The connectors endpoint provides extensive information about each connector configuration field.
Passthrough-Authorization
By default you can create configurations which work using a fixed username and password or token. However, if you require access to a specific user’s content only a few times, it can be quite excessive to create configurations for every individual user.
By specifying the Passthrough-Authorization header, you can override the credentials from a configuration for the
scope of a single request. There are two supported types of passthrough authorization:
Basic authorization allows you to override the username and password fields of a configuration. To use Basic
authorization you specify the following header: Passthrough-Authorization: Basic {AUTHORIZATION_STRING}. The
AUTHORIZATION_STRING is created by base64 encoding the string {USERNAME}:{PASSWORD}. For example, if your username
is mrclarke and your password is deborah94, you can create your AUTHORIZATION_STRING by base64 encoding the string
mrclarke:deborah94 to bXJjbGFya2U6ZGVib3JhaDk0. This means the header will be:
Passthrough-Authorization: Basic bXJjbGFya2U6ZGVib3JhaDk0.
Bearer authorization allows you to override the token field of a configuration. To use Bearer authorization you
specify the following header: Passthrough-Authorization: Bearer {TOKEN} where {TOKEN} is substituted by the desired token.
For example, if your token is 6gHrnAjJPvQAAAAAAAAMfg43gc, your header will be:
Passthrough-Authorization: Bearer 6gHrnAjJPvQAAAAAAAAMfg43gc.
This endpoint requires an access_token for scope configurations for a user with role CONFIG_ADMIN.
|
POST /v2/configurations ------ HTTP/1.1 201 Created Content-Type: application/json
$ curl 'https://demo-tenant.xill.io/v2/configurations' -i -X POST \
-H 'Authorization: Bearer <<YOUR_TOKEN>>' \
-H 'Content-Type: application/json' \
-d '{
"id" : "optional-id",
"name" : "A Temporary Folder",
"configurationType" : "FileSystem",
"passthroughAuthorization" : false,
"config" : {
"rootPath" : "file:///tmp/ApiDocumentationIT2156386203239471379/"
}
}'| Path | Type | Description |
|---|---|---|
|
|
The id of this configuration. |
|
|
The display name of this configuration. |
|
|
The underlying type of the configuration. |
|
|
The properties which are passed to the connector. |
|
|
Set this to true to enable passthrough authorization (default: false). |
HTTP/1.1 201 Created
{
"id" : "optional-id",
"name" : "A Temporary Folder",
"configurationType" : "FileSystem",
"passthroughAuthorization" : false,
"config" : {
"rootPath" : "file:///tmp/ApiDocumentationIT2156386203239471379/"
}
}2.8.4. Replace a Configuration
Replace one of your configurations, overwriting all fields with the given values. Missing fields are interpreted as having the value null.
See the connectors endpoint for more information about connector configuration fields.
The id cannot be changed using this method. The only way to achieve a similar result is to create a new configuration and delete the old one.
|
This endpoint requires an access_token for scope configurations for a user with role CONFIG_ADMIN.
|
PUT /v2/configurations/{configurationId}
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
$ curl 'https://demo-tenant.xill.io/v2/configurations/958c3fd74ce74e4bbc7c089173a3bfd3' -i -X PUT \
-H 'Authorization: Bearer <<YOUR_TOKEN>>' \
-H 'Content-Type: application/json' \
-d '{
"id" : null,
"name" : "\"New Name\"",
"configurationType" : "FileSystem",
"passthroughAuthorization" : false,
"config" : {
"rootPath" : "file:///tmp/ApiDocumentationIT12710218315461412477/"
}
}'| Path | Type | Description |
|---|---|---|
|
|
The id of this configuration. |
|
|
The display name of this configuration. |
|
|
The underlying type of the configuration. |
|
|
The properties which are passed to the connector. |
|
|
Set this to true to enable passthrough authorization (default: false). |
HTTP/1.1 200 OK
{
"id" : "958c3fd74ce74e4bbc7c089173a3bfd3",
"name" : "\"New Name\"",
"configurationType" : "FileSystem",
"passthroughAuthorization" : false,
"config" : {
"rootPath" : "file:///tmp/ApiDocumentationIT12710218315461412477/"
}
}2.8.5. Update a Configuration
Update (or patch) one of your configurations, overwriting only the included fields with the given values.
See the connectors endpoint for more information about connector configuration fields.
The config part of both configurations will be merged, with the new values taking precedence in case of field collisions
|
The id cannot be changed using this method. The only way to achieve a similar result is to create a new configuration and delete the old one.
|
This endpoint requires an access_token for scope configurations for a user with role CONFIG_ADMIN.
|
PATCH /v2/configurations/{configurationId}
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
$ curl 'https://demo-tenant.xill.io/v2/configurations/1941ec1bc3d14ffaa1ca1fa4d802f752' -i -X PATCH \
-H 'Authorization: Bearer <<YOUR_TOKEN>>' \
-H 'Content-Type: application/json' \
-d '{"config":{"rootPath":"file:///tmp/ApiDocumentationIT3404644430777429262/"}}'| Path | Type | Description |
|---|---|---|
|
|
The id of this configuration. |
|
|
The display name of this configuration. |
|
|
The underlying type of the configuration. |
|
|
The properties which are passed to the connector. |
|
|
Set this to true to enable passthrough authorization (default: false). |
HTTP/1.1 200 OK
{
"id" : "1941ec1bc3d14ffaa1ca1fa4d802f752",
"name" : "My filesystem configuration",
"configurationType" : "FileSystem",
"passthroughAuthorization" : false,
"config" : {
"rootPath" : "file:///tmp/ApiDocumentationIT3404644430777429262/"
}
}2.8.6. Delete a Configuration
Delete one of your configurations.
This endpoint requires an access_token for scope configurations for a user with role CONFIG_ADMIN.
|
DELETE /v2/configurations/{configurationId}
------
HTTP/1.1 204 No Content
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
$ curl 'https://demo-tenant.xill.io/v2/configurations/bb8dba55fea44cf48b8bdc24b41a3c82' -i -X DELETE \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'HTTP/1.1 204 No Content2.9. /configurations/contentScripts
2.9.1. List All Your Content Scripts
List all your content scripts.
This endpoint requires an access_token for scope contentscripts for a user with role CONTENTSCRIPT_ADMIN.
|
GET /v2/configurations/{configurationId}/contentScripts
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
$ curl 'https://demo-tenant.xill.io/v2/configurations/d8b79be82e6344d8aec91817eb004c68/contentScripts' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'HTTP/1.1 200 OK
[ {
"id" : "2c9180838e3c08a5018e3c09322c00ed",
"type" : "read",
"mimeType" : "application/FileData",
"description" : "This is the description of an example content script",
"passEntity" : false
} ]2.9.2. Get a Content Script
Get a content script.
This endpoint requires an access_token for scope contentscripts for a user with role CONTENTSCRIPT_ADMIN.
|
GET /v2/configurations/{configurationId}/contentScripts/{contentScriptId}
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The id of a configured content script. |
$ curl 'https://demo-tenant.xill.io/v2/configurations/f748163ab1d84c8699385602644d4c92/contentScripts/2c9180838e3c08a5018e3c09349d00f9' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'HTTP/1.1 200 OK
{
"id" : "2c9180838e3c08a5018e3c09349d00f9",
"type" : "read",
"mimeType" : "application/FileData",
"description" : "This is the description of an example content script",
"passEntity" : false
}2.9.3. Create a New Content Script
Create a content script with the given code, type, mimeType, description and passEntity fields.
The code, description and passEntity field are optional.
If no code is supplied, an identity script will be used.
This returns the created content script, with the id which can be used in other requests.
The script code is not returned, this can be requested via the code endpoint.
This endpoint requires an access_token for scope contentscripts for a user with role CONTENTSCRIPT_ADMIN.
|
POST /v2/configurations/{configurationId}/contentScripts
------
HTTP/1.1 201 Created
Content-Type: application/json
$ curl 'https://demo-tenant.xill.io/v2/configurations/70073c09c61047b6b557d3cddad25a20/contentScripts' -i -X POST \
-H 'Authorization: Bearer <<YOUR_TOKEN>>' \
-H 'Content-Type: application/json' \
-d '{
"id" : "2c9180838e3c08a5018e3c092dc900db",
"type" : "read",
"mimeType" : "application/FileData",
"description" : "This is the description of an example content script",
"passEntity" : false
}'| Path | Type | Description |
|---|---|---|
|
|
The id of a content script. |
|
|
How the content script is used, |
|
|
The mime type associated with this content script. |
|
|
The description of the content script. |
|
|
Whether to pass the entity object along with the content to the content script. |
HTTP/1.1 201 Created
{
"id" : "2c9180838e3c08a5018e3c092dc900db",
"type" : "read",
"mimeType" : "application/filedata",
"description" : "This is the description of an example content script",
"passEntity" : false
}2.9.4. Update a Content Script
Update one of your content scripts, overwriting all fields with the given values. If a field is not given, the old value will be used.
This endpoint requires an access_token for scope contentscripts for a user with role CONTENTSCRIPT_ADMIN.
|
PUT /v2/configurations/{configurationId}/contentScripts/{contentScriptId}
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The id of a configured content script. |
$ curl 'https://demo-tenant.xill.io/v2/configurations/72cf8fffefb4477a8740e884b75bec3a/contentScripts/2c9180838e3c08a5018e3c093a330119' -i -X PUT \
-H 'Authorization: Bearer <<YOUR_TOKEN>>' \
-H 'Content-Type: application/json' \
-d '{
"id" : "2c9180838e3c08a5018e3c093a330119",
"type" : "read",
"mimeType" : "application/FileData",
"description" : "This description has been updated",
"passEntity" : false
}'| Path | Type | Description |
|---|---|---|
|
|
The id of a content script. |
|
|
How the content script is used, |
|
|
The mime type associated with this content script. |
|
|
The description of the content script. |
|
|
Whether to pass the entity object along with the content to the content script. |
HTTP/1.1 200 OK
{
"id" : "2c9180838e3c08a5018e3c093a330119",
"type" : "read",
"mimeType" : "application/filedata",
"description" : "This description has been updated",
"passEntity" : false
}2.9.5. Delete a Content Script
Delete one of your content scripts.
This endpoint requires an access_token for scope contentscripts for a user with role CONTENTSCRIPT_ADMIN.
|
DELETE /v2/configurations/{configurationId}/contentScripts/{contentScriptId}
------
HTTP/1.1 204 No Content
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The id of a configured content script. |
$ curl 'https://demo-tenant.xill.io/v2/configurations/77d1d90c0ce14fbaa2491551df8d1a69/contentScripts/2c9180838e3c08a5018e3c09304e00e3' -i -X DELETE \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'HTTP/1.1 204 No Content2.9.6. Get the Code of a Content Script
Get the code of a content script.
This endpoint requires an access_token for scope contentscripts for a user with role CONTENTSCRIPT_ADMIN.
|
GET /v2/configurations/{configurationId}/contentScripts/{contentScriptId}/code
------
HTTP/1.1 200 OK
Content-Type: application/javascript
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The id of a configured content script. |
$ curl 'https://demo-tenant.xill.io/v2/configurations/e3f5e8f8fcb546da8c96bfa5db21d857/contentScripts/2c9180838e3c08a5018e3c0934fc00fb/code' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'HTTP/1.1 200 OK
//This is an example script2.9.7. Update the Code of a Content Script
Update the code of a content script.
This endpoint requires an access_token for scope contentscripts for a user with role CONTENTSCRIPT_ADMIN.
|
PUT /v2/configurations/{configurationId}/contentScripts/{contentScriptId}/code
------
HTTP/1.1 204 No Content
Content-Type: application/javascript
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The id of a configured content script. |
$ curl 'https://demo-tenant.xill.io/v2/configurations/e08084765e3a4ec3a96afea72ae3db52/contentScripts/2c9180838e3c08a5018e3c093a93011b/code' -i -X PUT \
-H 'Authorization: Bearer <<YOUR_TOKEN>>' \
-H 'Content-Type: application/javascript' \
-d 'module.exports = function(input) {
return input.content;
};'HTTP/1.1 204 No Content2.10. /configurations/queries
2.10.1. List All Your Named Queries
List all your named queries for a specific configuration.
This endpoint requires an access_token for scope query:configure for a user with role QUERY_ADMIN.
|
GET /v2/configurations/{configurationId}/queries
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
$ curl 'https://demo-tenant.xill.io/v2/configurations/4f486d782cec4026aae25136efe23e39/queries' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'| Path | Type | Description |
|---|---|---|
|
|
An array of all your named query for this configuration. |
|
|
The name of the query configuration. |
|
|
The template of the query, written for the target system. |
HTTP/1.1 200 OK
[ {
"name" : "my_query",
"template" : "parameter=${q_variable}"
} ]2.10.2. Get a Named Query
Get a named query.
This endpoint requires an access_token for scope query:configure for a user with role QUERY_ADMIN.
|
GET /v2/configurations/{configurationId}/queries/{queryName}
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The name of this query configuration. |
$ curl 'https://demo-tenant.xill.io/v2/configurations/efcbc4c5015b46beade34c7d3d80aebc/queries/my_query' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'| Path | Type | Description |
|---|---|---|
|
|
The name of the query configuration. |
|
|
The template of the query, written for the target system. |
HTTP/1.1 200 OK
{
"name" : "my_query",
"template" : "parameter=${q_variable}"
}2.10.3. Create a New Named Query
Create a named query with the given mandatory name and query fields. To execute a query see Execute a named query.
| The name of the query has to be unique per configuration. |
This returns the created named query configuration object, which can be referenced by its name in other requests.
This endpoint requires an access_token for scope query:configure for a user with role QUERY_ADMIN.
|
POST /v2/configurations/{configurationId}/queries/
------
HTTP/1.1 201 Created
Content-Type: application/json
$ curl 'https://demo-tenant.xill.io/v2/configurations/0ac70ed9f457474da4d1c52706159b0f/queries' -i -X POST \
-H 'Authorization: Bearer <<YOUR_TOKEN>>' \
-H 'Content-Type: application/json' \
-d '{
"name" : "my_query",
"template" : "parameter=${q_variable}"
}'| Path | Type | Description |
|---|---|---|
|
|
The name of the query configuration. |
|
|
The template of the query, written for the target system. |
HTTP/1.1 201 Created
{
"name" : "my_query",
"template" : "parameter=${q_variable}"
}2.10.4. Update a Named Query
Update one of your named query, overwriting the query field.
The name field will be ignored. To update it, you have to delete the faulty query and create a new one.
|
This endpoint requires an access_token for scope query:configure for a user with role QUERY_ADMIN.
|
PUT /v2/configurations/{configurationId}/queries/{queryName}
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The name of this query configuration. |
$ curl 'https://demo-tenant.xill.io/v2/configurations/a87bdc063d43492dbd6e7cd6bf603111/queries/my_query' -i -X PUT \
-H 'Authorization: Bearer <<YOUR_TOKEN>>' \
-H 'Content-Type: application/json' \
-d '{
"name" : "my_query",
"template" : "new_query"
}'| Path | Type | Description |
|---|---|---|
|
|
The name of the query configuration. |
|
|
The template of the query, written for the target system. |
HTTP/1.1 200 OK
{
"name" : "my_query",
"template" : "new_query"
}2.10.5. Delete a Named Query
Delete one of your named queries.
This endpoint requires an access_token for scope query:configure for a user with role QUERY_ADMIN.
|
DELETE /v2/configurations/{configurationId}/queries/{queryName}
------
HTTP/1.1 204 No Content
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The name of this query configuration. |
$ curl 'https://demo-tenant.xill.io/v2/configurations/183bbe1b1ab94695a520fad00ee778b7/queries/my_query' -i -X DELETE \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'HTTP/1.1 204 No Content2.11. /users
2.11.1. List All Your Users
List all your users.
This endpoint requires an access_token for scope users for a user with role USER_ADMIN.
|
GET /v2/users ------ HTTP/1.1 200 OK Content-Type: application/json
$ curl 'https://demo-tenant.xill.io/v2/users' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'| Path | Type | Description |
|---|---|---|
|
|
An array of all users. |
HTTP/1.1 200 OK
[ {
"id" : "2c9180838e3c08a5018e3c08f9360069",
"username" : "demo-user",
"displayName" : "Demo user",
"email" : "demo-user@example.com",
"roles" : [ "USER_ADMIN", "ENTITY_ADMIN", "CONTENTSCRIPT_ADMIN", "CONFIG_ADMIN", "QUERY_ADMIN", "SEARCH", "RPC_USER", "ENTITY_USER" ]
}, {
"id" : "2c9180838e3c08a5018e3c08f975006a",
"username" : "USER_ADMIN",
"displayName" : "USER_ADMIN",
"roles" : [ "USER_ADMIN" ]
}, {
"id" : "2c9180838e3c08a5018e3c08f9b2006b",
"username" : "CONFIG_ADMIN",
"displayName" : "CONFIG_ADMIN",
"roles" : [ "CONFIG_ADMIN" ]
}, {
"id" : "2c9180838e3c08a5018e3c08f9ef006c",
"username" : "ENTITY_ADMIN",
"displayName" : "ENTITY_ADMIN",
"roles" : [ "ENTITY_ADMIN" ]
}, {
"id" : "2c9180838e3c08a5018e3c08fa2c006d",
"username" : "ENTITY_USER",
"displayName" : "ENTITY_USER",
"roles" : [ "ENTITY_USER" ]
}, {
"id" : "2c9180838e3c08a5018e3c08fa69006e",
"username" : "CONTENTSCRIPT_ADMIN",
"displayName" : "CONTENTSCRIPT_ADMIN",
"roles" : [ "CONTENTSCRIPT_ADMIN" ]
}, {
"id" : "2c9180838e3c08a5018e3c08faa5006f",
"username" : "QUERY_ADMIN",
"displayName" : "QUERY_ADMIN",
"roles" : [ "QUERY_ADMIN" ]
}, {
"id" : "2c9180838e3c08a5018e3c08fae20070",
"username" : "RPC_USER",
"displayName" : "RPC_USER",
"roles" : [ "RPC_USER" ]
}, {
"id" : "2c9180838e3c08a5018e3c08fb1e0071",
"username" : "SEARCH",
"displayName" : "SEARCH",
"roles" : [ "SEARCH" ]
}, {
"id" : "2c9180838e3c08a5018e3c08ff4d0074",
"username" : "new-user",
"displayName" : "New user",
"email" : "new-user@example.com",
"roles" : [ "ENTITY_ADMIN", "ENTITY_USER" ]
} ]2.11.2. Get a User
Get one of your users.
This endpoint requires an access_token for scope users for a user with role USER_ADMIN.
|
GET /v2/users/{username}
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The name of the user. |
$ curl 'https://demo-tenant.xill.io/v2/users/demo-user' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'| Path | Type | Description |
|---|---|---|
|
|
The unique id for the user. |
|
|
The name of the user. |
|
|
The display name of the user. |
|
|
The e-mail address of the user. |
|
|
The authorities of the user. |
HTTP/1.1 200 OK
{
"id" : "2c9180838e3c08a5018e3c08f9360069",
"username" : "demo-user",
"displayName" : "Demo user",
"email" : "demo-user@example.com",
"roles" : [ "USER_ADMIN", "ENTITY_ADMIN", "CONTENTSCRIPT_ADMIN", "CONFIG_ADMIN", "QUERY_ADMIN", "SEARCH", "RPC_USER", "ENTITY_USER" ]
}2.11.3. Create a New User
Create a user with the given username, password, displayName and email.
This returns the created user.
| The password has to be at least 10 characters long, and the lowercased password cannot contain the lowercased username. |
If the roles field is omitted, the user will be granted all roles.
|
This endpoint requires an access_token for scope users for a user with role USER_ADMIN.
|
POST /v2/users ------ HTTP/1.1 201 Created Content-Type: application/json
$ curl 'https://demo-tenant.xill.io/v2/users' -i -X POST \
-H 'Authorization: Bearer <<YOUR_TOKEN>>' \
-H 'Content-Type: application/json' \
-d '{
"password" : "U2VjcmV0cyE=",
"displayName" : "New user",
"roles" : [ "ENTITY_ADMIN", "ENTITY_USER" ],
"email" : "new-user@example.com",
"username" : "new-user"
}'| Path | Type | Description |
|---|---|---|
|
|
The unique id for the user. |
|
|
The name of the user. |
|
|
The display name of the user. |
|
|
The e-mail address of the user. |
|
|
The authorities of the user. |
HTTP/1.1 201 Created
{
"id" : "2c9180838e3c08a5018e3c08ff4d0074",
"username" : "new-user",
"displayName" : "New user",
"email" : "new-user@example.com",
"roles" : [ "ENTITY_ADMIN", "ENTITY_USER" ]
}2.11.4. Update a User
Update one of your users, overwriting all fields with the given values. If a field is not given, the old value will be used.
This endpoint requires an access_token for scope users for a user with role USER_ADMIN.
|
PUT /v2/users/{username}
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The name of the user. |
$ curl 'https://demo-tenant.xill.io/v2/users/demo-user' -i -X PUT \
-H 'Authorization: Bearer <<YOUR_TOKEN>>' \
-H 'Content-Type: application/json' \
-d '{
"password" : "Z2lwaHkuY29tL2VtYmVkLzdwdDloQlhRUjlJMmM=",
"displayName" : "Demo user",
"roles" : [ "ENTITY_ADMIN", "ENTITY_USER" ],
"email" : "demo-user@example.com",
"username" : "demo-user"
}'| Path | Type | Description |
|---|---|---|
|
|
The unique id for the user. |
|
|
The name of the user. |
|
|
The display name of the user. |
|
|
The e-mail address of the user. |
|
|
The authorities of the user. |
HTTP/1.1 200 OK
{
"id" : "2c9180838e3c08a5018e3c08f9360069",
"username" : "demo-user",
"displayName" : "Demo user",
"email" : "demo-user@example.com",
"roles" : [ "ENTITY_ADMIN", "ENTITY_USER" ]
}2.11.5. Delete a User
Delete one of your users.
This endpoint requires an access_token for scope users for a user with role USER_ADMIN.
|
DELETE /v2/users/{username}
------
HTTP/1.1 204 No Content
| Parameter | Description |
|---|---|
|
The name of the user. |
$ curl 'https://demo-tenant.xill.io/v2/users/delete-me' -i -X DELETE \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'HTTP/1.1 204 No Content2.12. /user
2.12.1. Get Your Current User
Get your user profile.
This endpoint requires an access_token for scope user.
|
GET /v2/user ------ HTTP/1.1 200 OK Content-Type: application/json
$ curl 'https://demo-tenant.xill.io/v2/user' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'| Path | Type | Description |
|---|---|---|
|
|
The unique id for the user. |
|
|
The name of the user. |
|
|
The display name of the user. |
|
|
The e-mail address of the user. |
|
|
The authorities of the user. |
HTTP/1.1 200 OK
{
"id" : "2c9180838e3c08a5018e3c091a9100b6",
"username" : "demo-user",
"displayName" : "Demo user",
"email" : "demo-user@example.com",
"roles" : [ "USER_ADMIN", "ENTITY_ADMIN", "CONTENTSCRIPT_ADMIN", "CONFIG_ADMIN", "QUERY_ADMIN", "SEARCH", "RPC_USER", "ENTITY_USER" ]
}2.12.2. Update Your Current User
Update your user profile, overwriting all fields with the given values.
If a field is not given, the old value will be used.
Note that the username and roles fields cannot be updated, that can be done with the /users endpoint.
This endpoint requires an access_token for scope user.
|
PUT /v2/user ------ HTTP/1.1 200 OK Content-Type: application/json
$ curl 'https://demo-tenant.xill.io/v2/user' -i -X PUT \
-H 'Authorization: Bearer <<YOUR_TOKEN>>' \
-H 'Content-Type: application/json' \
-d '{
"password" : "updated-demo-password",
"displayName" : "Updated Demo User",
"email" : "updated-demo-user@example.com"
}'| Path | Type | Description |
|---|---|---|
|
|
The unique id for the user. |
|
|
The name of the user. |
|
|
The display name of the user. |
|
|
The e-mail address of the user. |
|
|
The authorities of the user. |
HTTP/1.1 200 OK
{
"id" : "2c9180838e3c08a5018e3c091a9100b6",
"username" : "demo-user",
"displayName" : "Updated Demo User",
"email" : "updated-demo-user@example.com",
"roles" : [ "USER_ADMIN", "ENTITY_ADMIN", "CONTENTSCRIPT_ADMIN", "CONFIG_ADMIN", "QUERY_ADMIN", "SEARCH", "RPC_USER", "ENTITY_USER" ]
}2.13. /connectors
2.13.1. Retrieve the Connector Information
Get information about all available connectors.
The configurationType is the type of configuration that can be created, and the config contains each configurable element for that connector.
Some connector configuration fields have a default value, for which relevant information is available in the default field.
|
Some connector configuration fields contain sensitive information. For those fields, the secret property is set to true, and their values are obfuscated.
|
All default values for which mustDefaultWith is not empty must be specified or omitted together.
|
GET /v2/connectors ------ HTTP/1.1 200 OK Content-Type: application/json
$ curl 'https://demo-tenant.xill.io/v2/connectors' -i -X GET| Path | Type | Description |
|---|---|---|
|
|
An array of information of all configurations in the connectors. |
HTTP/1.1 200 OK
[ {
"configurationType" : "Aem",
"description" : "Adobe Experience Manager brings your content management system (CMS) and digital asset management (DAM) together — in one place.",
"config" : [ {
"name" : "baseUrl",
"type" : "URL",
"required" : true,
"description" : "The URL of the AEM host.",
"longDescription" : "The base URL of the AEM host.",
"example" : "https://aem.xillio.com:4502",
"secret" : false
}, {
"name" : "username",
"type" : "STRING",
"required" : true,
"description" : "The username of an account.",
"longDescription" : "The username of an account with permissions to access CRX.",
"example" : "username",
"secret" : false
}, {
"name" : "password",
"type" : "STRING",
"required" : true,
"description" : "The password of the account.",
"longDescription" : "The password of an account with permissions to access CRX.",
"example" : "password",
"secret" : false
}, {
"name" : "workspace",
"type" : "STRING",
"required" : false,
"description" : "The JCR workspace to access.",
"longDescription" : "The JCR workspace to access.",
"example" : "NO_EXAMPLE",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : "crx.default"
}
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "NOT_IMPLEMENTED",
"contentTypeDiscovery" : "NOT_IMPLEMENTED",
"namedQueries" : "NOT_IMPLEMENTED",
"entityScope" : "SUPPORTED",
"translationScope" : "NOT_IMPLEMENTED",
"versionScope" : "NOT_IMPLEMENTED",
"metadataScope" : "NOT_IMPLEMENTED",
"rpc" : "SUPPORTED",
"search" : "NOT_IMPLEMENTED",
"pagination" : "SUPPORTED"
}
}, {
"configurationType" : "Bitbucket",
"description" : "Bitbucket is a web-based version control repository hosting service for source code and development projects.",
"config" : [ {
"name" : "baseUrl",
"type" : "URL",
"required" : false,
"description" : "The URL of the Bitbucket API.",
"longDescription" : "The base URL of the Bitbucket v2 cloud service.",
"example" : "NO_EXAMPLE",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : "https://api.bitbucket.org/2.0"
}
}, {
"name" : "username",
"type" : "STRING",
"required" : true,
"description" : "The username of an account.",
"longDescription" : "The username of an account on Bitbucket (not the email address).",
"example" : "username",
"secret" : false
}, {
"name" : "password",
"type" : "STRING",
"required" : true,
"description" : "The password of the account.",
"longDescription" : "The password of the account.",
"example" : "password",
"secret" : true
}, {
"name" : "owner",
"type" : "STRING",
"required" : false,
"description" : "The owner of the repositories. If this is not provided, the username is used as owner.",
"longDescription" : "The owner for which to select repositories. When not provided, the connector will use the `username` as owner.\n\nThe repositories shown with this setting are only the ones owned by the owner, not the repositories to which the user has access to.",
"example" : "repository-owner",
"secret" : false
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "SUPPORTED",
"namedQueries" : "NOT_IMPLEMENTED",
"entityScope" : "SUPPORTED",
"translationScope" : "NOT_AVAILABLE",
"versionScope" : "SUPPORTED",
"metadataScope" : "NOT_IMPLEMENTED",
"rpc" : "SUPPORTED",
"search" : "NOT_IMPLEMENTED",
"pagination" : "NOT_IMPLEMENTED"
}
}, {
"configurationType" : "Box",
"description" : "Box Drive is the incredibly simple way to stream all of your files — even millions of files — right to your desktop, taking up very little hard drive space.",
"config" : [ {
"name" : "baseUrl",
"type" : "URL",
"required" : false,
"description" : "The URL of the Box API.",
"longDescription" : "The base URL of the Box API.",
"example" : "NO_EXAMPLE",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : "https://api.box.com/2.0"
}
}, {
"name" : "uploadUrl",
"type" : "URL",
"required" : false,
"description" : "The URL of the Box API upload endpoint.",
"longDescription" : "The URL of the Box API upload endpoint.",
"example" : "NO_EXAMPLE",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : "https://upload.box.com/api/2.0"
}
}, {
"name" : "clientSecret",
"type" : "STRING",
"required" : false,
"description" : "The client secret of the Box Application.",
"longDescription" : "The Box application secret. Required when `refreshToken` is set.",
"example" : "kHsek3Jpji8tgFTcwcnqosfYnxO4unQA",
"secret" : true
}, {
"name" : "clientId",
"type" : "STRING",
"required" : false,
"description" : "The client id of the Box Application.",
"longDescription" : "The Box application client id. Required when `refreshToken` is set.",
"example" : "m1rvfFhvTCe2a5n7u4eElmOfvvE6WumL",
"secret" : false
}, {
"name" : "token",
"type" : "STRING",
"required" : false,
"description" : "An access token.",
"longDescription" : "A Box OAuth2 token.\n\nWhen set, `refreshToken`, `clientId` and `clientSecret` are not required. It can be useful for testing, or if your application handles refreshing tokens.",
"secret" : true
}, {
"name" : "refreshToken",
"type" : "STRING",
"required" : false,
"description" : "A refresh token.",
"longDescription" : "An OAuth2 refresh token.",
"example" : "xi88SOqkEht8lb6fGMvsYJWQne2kUC3gTDeAecQXK6XUkcmxBa1fe1s3zDqWLMyS",
"secret" : true
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "SUPPORTED",
"namedQueries" : "NOT_IMPLEMENTED",
"entityScope" : "SUPPORTED",
"translationScope" : "NOT_AVAILABLE",
"versionScope" : "NOT_IMPLEMENTED",
"metadataScope" : "SUPPORTED",
"rpc" : "SUPPORTED",
"search" : "SUPPORTED",
"pagination" : "NOT_IMPLEMENTED"
}
}, {
"configurationType" : "Contentful",
"description" : "Contentful is the API-first content management platform to create, manage and publish content on any digital channel.",
"config" : [ {
"name" : "token",
"type" : "STRING",
"required" : true,
"description" : "The personal access token of your Contentful Management API",
"longDescription" : "The Content management access token.",
"example" : "aHR0cHM6Ly9tZWRpYS5tYWtlYW1lbWUub3JnL2NyZWF0ZWQvZG8teW91LXdhbnQtbmVkZ3Y2LmpwZw==",
"secret" : true
}, {
"name" : "spaceId",
"type" : "STRING",
"required" : false,
"description" : "The space id of your Contentful Management API",
"longDescription" : "The ID of the Contentful space you want to access. This value is optional. When not provided the connector will expose all the spaces that the tokens allows accessing.",
"example" : "43bhs4uagphk",
"secret" : false
}, {
"name" : "environmentId",
"type" : "STRING",
"required" : false,
"description" : "The environment id of your Contentful Management API",
"longDescription" : "The environment id of your Contentful Management API. It is necessary to add spaceId if you add environmentId.",
"example" : "master",
"secret" : false
}, {
"name" : "sourceLanguageCode",
"type" : "STRING",
"required" : true,
"description" : "To provide source language for download entry data for translation",
"longDescription" : "Configure the code of the language you consider a source language for the translations. This defines what values the connector exports as content that needs to be translated.",
"example" : "en-US",
"secret" : false
}, {
"name" : "getOnlyTranslationFields",
"type" : "BOOLEAN",
"required" : false,
"description" : "Setting this value to true, the connector will extract only fields of your models that are enabled for translation.",
"longDescription" : "Setting this value to true, the connector will extract only fields of your models that are enabled for translation.",
"example" : "false",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : false
}
}, {
"name" : "exposeLinkedEntitiesAsChildren",
"type" : "BOOLEAN",
"required" : false,
"description" : "Setting this value to true, the connector will expose linked and referenced items of an Entry as children of the Entry.",
"longDescription" : "Setting this value to true, the connector will expose linked and referenced items of an Entry as children of the Entry. Setting it to false or leaving it out, there will be no children of Entries.",
"example" : "false",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : false
}
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "NOT_IMPLEMENTED",
"namedQueries" : "NOT_IMPLEMENTED",
"entityScope" : "SUPPORTED",
"translationScope" : "NOT_IMPLEMENTED",
"versionScope" : "NOT_IMPLEMENTED",
"metadataScope" : "NOT_IMPLEMENTED",
"rpc" : "NOT_IMPLEMENTED",
"search" : "NOT_IMPLEMENTED",
"pagination" : "NOT_IMPLEMENTED"
}
}, {
"configurationType" : "Dropbox",
"description" : "Dropbox is a modern workspace designed to reduce busywork—so you can focus on the things that matter.",
"config" : [ {
"name" : "token",
"type" : "STRING",
"required" : true,
"description" : "The access token from the Xillio app in Dropbox.",
"longDescription" : "A Dropbox API token.",
"example" : "aHR0cHM6Ly9tZWRpYS5tYWtlYW1lbWUub3JnL2NyZWF0ZWQvZG8teW91LXdhbnQtbmVkZ3Y2LmpwZw==",
"secret" : true
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "SUPPORTED",
"namedQueries" : "SUPPORTED",
"entityScope" : "SUPPORTED",
"translationScope" : "NOT_AVAILABLE",
"versionScope" : "SUPPORTED",
"metadataScope" : "SUPPORTED",
"rpc" : "SUPPORTED",
"search" : "SUPPORTED",
"pagination" : "NOT_IMPLEMENTED"
}
}, {
"configurationType" : "Drupal",
"description" : "Drupal is an open source platform for building amazing digital experiences. It's made by a dedicated community. Anyone can use it, and it will always be free.",
"config" : [ {
"name" : "username",
"type" : "STRING",
"required" : true,
"description" : "The username of an account.",
"longDescription" : "The username of an account on Drupal.",
"example" : "username",
"secret" : false
}, {
"name" : "password",
"type" : "STRING",
"required" : true,
"description" : "The password of the account.",
"longDescription" : "The password of the account.",
"example" : "password",
"secret" : true
}, {
"name" : "baseUrl",
"type" : "URL",
"required" : true,
"description" : "The URL of the Drupal instance including the path to the JSON:API module.",
"longDescription" : "The URL to the JSON:API module of Drupal.",
"example" : "https://my-drupal-website:8084/jsonapi",
"secret" : false
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "NOT_IMPLEMENTED",
"namedQueries" : "NOT_IMPLEMENTED",
"entityScope" : "SUPPORTED",
"translationScope" : "SUPPORTED",
"versionScope" : "NOT_IMPLEMENTED",
"metadataScope" : "NOT_IMPLEMENTED",
"rpc" : "SUPPORTED",
"search" : "NOT_IMPLEMENTED",
"pagination" : "SUPPORTED"
}
}, {
"configurationType" : "Egnyte",
"description" : "Egnyte CONNECT: Secure File Sharing & Collaboration.",
"config" : [ {
"name" : "address",
"type" : "STRING",
"required" : true,
"description" : "The URL of the Egnyte instance.",
"longDescription" : "The base URL of the Egnyte instance.",
"example" : "https://example.egnyte.com",
"secret" : false
}, {
"name" : "token",
"type" : "STRING",
"required" : true,
"description" : "An access token.",
"longDescription" : "An Egnyte OAuth2 token.",
"example" : "aHR0cHM6Ly9tZWRpYS5tYWtlYW1lbWUub3JnL2NyZWF0ZWQvZG8teW91LXdhbnQtbmVkZ3Y2LmpwZw==",
"secret" : true
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "SUPPORTED",
"namedQueries" : "NOT_IMPLEMENTED",
"entityScope" : "SUPPORTED",
"translationScope" : "NOT_AVAILABLE",
"versionScope" : "SUPPORTED",
"metadataScope" : "NOT_IMPLEMENTED",
"rpc" : "SUPPORTED",
"search" : "NOT_IMPLEMENTED",
"pagination" : "NOT_IMPLEMENTED"
}
}, {
"configurationType" : "Episerver10",
"description" : "Episerver is a global software company offering web content management (WCM) (or CMS), digital commerce, and digital marketing, through the Episerver Digital Experience Cloud software platform.",
"config" : [ {
"name" : "baseUrl",
"type" : "URL",
"required" : true,
"description" : "The URL of the Episerver api extension.",
"longDescription" : "The URL of the Episerver instance.",
"example" : "http://my-domain.com:49700/episerverapi",
"secret" : false
}, {
"name" : "username",
"type" : "STRING",
"required" : true,
"description" : "The username of an account.",
"longDescription" : "The username of an account on Episerver.",
"example" : "username",
"secret" : false
}, {
"name" : "password",
"type" : "STRING",
"required" : true,
"description" : "The username of an account.",
"longDescription" : "The password of the account.",
"example" : "password",
"secret" : true
}, {
"name" : "token",
"type" : "STRING",
"required" : false,
"description" : "An access token.",
"longDescription" : "An Episerver OAuth2 token.\n\nA token lasts 5 minutes after which a new one will be requested.\n\nOptional if supplying a `username` and `password`.",
"secret" : true
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "NOT_IMPLEMENTED",
"namedQueries" : "NOT_IMPLEMENTED",
"entityScope" : "SUPPORTED",
"translationScope" : "SUPPORTED",
"versionScope" : "NOT_IMPLEMENTED",
"metadataScope" : "NOT_IMPLEMENTED",
"rpc" : "SUPPORTED",
"search" : "NOT_IMPLEMENTED",
"pagination" : "NOT_IMPLEMENTED"
}
}, {
"configurationType" : "Filenet",
"description" : "IBM FileNet Content Manager is document management engine with enterprise content, security and storage features plus process management capabilities.",
"config" : [ {
"name" : "baseUrl",
"type" : "URL",
"required" : true,
"description" : "The URL of the FileNet server API extension.",
"longDescription" : "The URL of the FileNet server API extension.",
"example" : "http://filenet.xillio.com:9080/wsi/FNCEWS40MTOM",
"secret" : false
}, {
"name" : "username",
"type" : "STRING",
"required" : true,
"description" : "The username of an account.",
"longDescription" : "The username of an account on Filenet.",
"example" : "username",
"secret" : false
}, {
"name" : "password",
"type" : "STRING",
"required" : true,
"description" : "The password of the account.",
"longDescription" : "The password of the account.",
"example" : "password",
"secret" : true
}, {
"name" : "objectstore",
"type" : "STRING",
"required" : true,
"description" : "The name of the object store to which to connect.",
"longDescription" : "The name of the object store to which to connect.",
"example" : "objectstore",
"secret" : false
}, {
"name" : "stanza",
"type" : "STRING",
"required" : false,
"description" : "The communication protocol to use.",
"longDescription" : "The communication protocol to use.\n\nIf not sure about what value to use for stanza, leave empty, the Web Service Interface will be used by default.",
"example" : "NO_EXAMPLE",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : "FileNetP8WSI"
}
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "SUPPORTED",
"namedQueries" : "SUPPORTED",
"entityScope" : "SUPPORTED",
"translationScope" : "NOT_AVAILABLE",
"versionScope" : "SUPPORTED",
"metadataScope" : "SUPPORTED",
"rpc" : "SUPPORTED",
"search" : "NOT_IMPLEMENTED",
"pagination" : "SUPPORTED"
}
}, {
"configurationType" : "GitLab",
"description" : "GitLab is a web-based Git-repository manager providing wiki, issue-tracking and CI/CD pipeline features.",
"config" : [ {
"name" : "baseUrl",
"type" : "URL",
"required" : false,
"description" : "The URL of the GitLab instance.",
"longDescription" : "The base URL to the GitLab instance.",
"example" : "NO_EXAMPLE",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : "https://gitlab.com"
}
}, {
"name" : "clientId",
"type" : "STRING",
"required" : false,
"description" : "The application id.",
"longDescription" : "The GitLab application client id. Required when `refreshToken` is set.",
"example" : "client-id",
"secret" : false
}, {
"name" : "clientSecret",
"type" : "STRING",
"required" : false,
"description" : "The application secret.",
"longDescription" : "The GitLab application secret. Required when `refreshToken` is set.",
"example" : "client-secret",
"secret" : true
}, {
"name" : "token",
"type" : "STRING",
"required" : false,
"description" : "A GitLab personal access token or an OAuth2 token",
"longDescription" : "A GitLab personal access token, or a GitLab OAuth2 token.\n\nWhen set, `refreshToken`, `clientId` and `clientSecret` are not required.",
"secret" : true
}, {
"name" : "refreshToken",
"type" : "STRING",
"required" : false,
"description" : "A refresh token.",
"longDescription" : "An OAuth2 refresh token.\n\nSee <<gitlab-credentials>> for information on acquiring a refresh token.",
"example" : "fdb8fdbecf1d03ce5e6125c067733c0d51de209c",
"secret" : true
}, {
"name" : "projectId",
"type" : "STRING",
"required" : true,
"description" : "The id or path of the git repository.",
"longDescription" : "The id of the GitLab project.\n\nIt can be specified either by name (e.g. `MyUser/MyProject` or `MyOrganization/MyProject`) or by a numeric identifier (e.g. `10262206`), which can be found on the main page of the project.",
"example" : "MyGroup/MyProject",
"secret" : false
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "NOT_IMPLEMENTED",
"namedQueries" : "NOT_IMPLEMENTED",
"entityScope" : "SUPPORTED",
"translationScope" : "NOT_AVAILABLE",
"versionScope" : "NOT_IMPLEMENTED",
"metadataScope" : "NOT_IMPLEMENTED",
"rpc" : "SUPPORTED",
"search" : "NOT_IMPLEMENTED",
"pagination" : "NOT_IMPLEMENTED"
}
}, {
"configurationType" : "GoogleDrive",
"description" : "A safe place for all your files.",
"config" : [ {
"name" : "baseUrl",
"type" : "URL",
"required" : false,
"description" : "The URL of the Google Drive API.",
"longDescription" : "The base URL of the Google Drive API.",
"example" : "NO_EXAMPLE",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : "https://www.googleapis.com"
}
}, {
"name" : "oauthUrl",
"type" : "URL",
"required" : false,
"description" : "The token URL of the Google authorization server.",
"longDescription" : "The token URL of the Google authorization server.",
"example" : "NO_EXAMPLE",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : "https://www.googleapis.com/oauth2/v4/token"
}
}, {
"name" : "clientId",
"type" : "STRING",
"required" : false,
"description" : "The client id of your Google API application.",
"longDescription" : "The Google Drive application client id. Required when `refreshToken` is set.",
"example" : "826514876365-m4hltubt3d3tvu7iu2875m5pvum0fm8l.apps.googleusercontent.com",
"secret" : false
}, {
"name" : "clientSecret",
"type" : "STRING",
"required" : false,
"description" : "The client secret of your Google API application.",
"longDescription" : "The Google Drive application secret. Required when `refreshToken` is set.",
"example" : "BAHEfQjVAN-GVZ9IV9EPbPg_",
"secret" : true
}, {
"name" : "token",
"type" : "STRING",
"required" : false,
"description" : "An access token.",
"longDescription" : "A Google Drive OAuth2 token.\n\nWhen set, `refreshToken`, `clientId` and `clientSecret` are not required. It can be useful for testing, or if your application handles refreshing tokens.",
"secret" : true
}, {
"name" : "refreshToken",
"type" : "STRING",
"required" : false,
"description" : "A refresh token.",
"longDescription" : "An OAuth2 refresh token.\n\nSee <<googledrive-refresh-token>> for information on acquiring a refresh token.",
"example" : "1/CWEaui3J_4X5sQlYGP0S4lwZ6er59YsWx6jiPrflAiA",
"secret" : true
}, {
"name" : "mimeTypeMapping",
"type" : "MAP",
"required" : false,
"description" : "The mapping of Google mimeTypes to an exportable mimeTypes.",
"longDescription" : "It is not possible to download the Google Docs format via Xillio API directly.\n\nThe `mimeTypeMapping` field is required to make the downloading and exporting the content of the Google Docs format files possible by converting it into any other compatible format.\n\nThe `mimeTypeMapping` field is an another JSON object. So, it can be either `null` or have the standard JSON structure like:\n\n[source]\n----\n{\n \"application/vnd.google-apps.document\": \"text/plain\",\n \"application/vnd.google-apps.spreadsheet\": \"text/csv\"\n}\n----\nThe key must be a `googleMimeType` and value is an `exportMimeType`\n\nIf the `googleMimeType` will not be compatible with `exportMimeType`, e.g.\n[source]\n----\n{\n \"application/vnd.google-apps.document\": \"image/jpeg\",\n ...\n}\n----\nwhat means you are trying to export a document format as a `JPG image`, you will get an error\n[source]\n----\n{\n \"errorId\": \"27d9e2d0-0336-4ead-ad8f-a5348532426e\",\n \"message\": \"Export Mime Type [image/jpeg] not supported by [application/vnd.google-apps.document]\",\n \"error\": \"Bad Request\",\n \"status\": 400,\n \"timestamp\": \"2021-11-25T14:19:36.891+01:00\",\n \"errorType\": \"InvalidConfiguration\",\n \"path\": \"/v2/configurations\",\n \"parameters\": {}\n}\n----\nPlease refer to the https://developers.google.com/drive/api/v3/ref-export-formats[official Google documentation] to find everything out about different mimeTypes and their compatibility.\n\nEach Google doc format can be exported only into one format in each distinct mimeTypeMapping. If you enter several export formats for the same Google Docs format e.g.\n[source]\n----\n{\n \"application/vnd.google-apps.document\": \"text/plain\",\n \"application/vnd.google-apps.document\": \"application/rtf\",\n \"application/vnd.google-apps.spreadsheet\": \"text/csv\"\n}\n----\nonly the last one will be used.\n\nAs were said, the `mimeTypeMapping` field is a JSON object but you must provide map only. You can you neither arrays nor nested objects.\n\n\nIf you don't set up the `mimeTypeMapping` field or miss a desired format and try to download a Google Doc, you will get an error\n[source]\n----\n{\n \"errorId\": \"b2811db5-21fe-4cb7-9213-edd39c56725b\",\n \"message\": \"Configuration for googleMimeType [<missing mimeType>] not added\",\n \"error\": \"Method Not Allowed\",\n \"status\": 405,\n \"timestamp\": \"2021-11-25T13:52:04.415+01:00\",\n \"errorType\": \"OperationNotAllowed\",\n \"path\": \"/v2/contents/googledrive/<file-id>\",\n \"parameters\": {}\n}\n----",
"example" : "{ \"application/vnd.google-apps.document\": \"text/plain\", \"application/vnd.google-apps.spreadsheet\":\"text/csv\" }",
"secret" : false
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "SUPPORTED",
"namedQueries" : "SUPPORTED",
"entityScope" : "SUPPORTED",
"translationScope" : "NOT_AVAILABLE",
"versionScope" : "SUPPORTED",
"metadataScope" : "SUPPORTED",
"rpc" : "SUPPORTED",
"search" : "SUPPORTED",
"pagination" : "NOT_IMPLEMENTED"
}
}, {
"configurationType" : "JsonRpc",
"description" : "Configuration for an external connector that exposes the JSON RPC API.",
"config" : [ {
"name" : "baseUrl",
"type" : "URL",
"required" : true,
"description" : "The URL of the connector jsonrpc endpoint",
"longDescription" : "The URL of the remote JSON RPC connector endpoint that is going to execute the requests for this configuration.",
"example" : "http://custom-connector:8887/json-rpc",
"secret" : false
}, {
"name" : "skipSslValidation",
"type" : "BOOLEAN",
"required" : false,
"description" : "Ignore SSL trust chain verification for the external connector",
"longDescription" : "When set to `true`, the connector will skip validation of the trust chain when connecting to the external connector with the `HTTPS` protocol, allowing to use self-signed certificates.\n\nWARNING: _Only for testing_: should be left to `false` in production as it will not prevent spoofing and man in the middle attacks.",
"example" : "false",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : false
}
}, {
"name" : "configuration",
"type" : "MAP",
"required" : true,
"description" : "The external connector configuration",
"longDescription" : "The external JSON RPC connector configuration fields in the form a JSON object with field names as keys and field values as values.\n\nNOTE: Arrays, nested objects and null values are not supported in this configuration object.\n\nFor example, if the external JSON RPC connector needs a `baseUrl` and a `token` field, the `configuration` map would look as follows:\n\n```\n{\n \"baseUrl\" : \"https://myhost.com/myCms\",\n \"token\" : \"mytokenforauthenticationandauthorization\"\n}\n```\n\nNOTE: It is important not to confuse the `baseUrl` of the JSON RPC connector configuration, that points to the external _connector_, with the `baseUrl` field of the external connector configuration that points to the _target system_.",
"example" : "{ \"baseUrl\": \"https://mycms/store\", \"token\":\"ljdadn234wqnadnn4\" }",
"secret" : false
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "SUPPORTED",
"namedQueries" : "SUPPORTED",
"entityScope" : "SUPPORTED",
"translationScope" : "SUPPORTED",
"versionScope" : "SUPPORTED",
"metadataScope" : "SUPPORTED",
"rpc" : "SUPPORTED",
"search" : "SUPPORTED",
"pagination" : "SUPPORTED"
}
}, {
"configurationType" : "OneDrive",
"description" : "OneDrive is Microsoft's service for hosting files in the \"cloud\", that's available for free to all the owners of a Microsoft account and offers users a simple way to store, sync and share all kinds of files, with other people and devices.",
"config" : [ {
"name" : "baseUrl",
"type" : "URL",
"required" : false,
"description" : "The URL of the OneDrive API.",
"longDescription" : "The base URL of the OneDrive API.",
"example" : "NO_EXAMPLE",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : "https://graph.microsoft.com/v1.0/me/drive/root"
}
}, {
"name" : "redirectUri",
"type" : "STRING",
"required" : false,
"description" : "The OAuth redirect URI.",
"longDescription" : "The URI where the user is redirected to after authorization is completed.",
"example" : "https://xillio.com/callback",
"secret" : false
}, {
"name" : "clientId",
"type" : "STRING",
"required" : false,
"description" : "The client id of your application registered with OneDrive.",
"longDescription" : "The OneDrive application client id. Required when `refreshToken` is set.",
"example" : "client-id",
"secret" : false
}, {
"name" : "clientSecret",
"type" : "STRING",
"required" : false,
"description" : "The client secret of your application registered with OneDrive.",
"longDescription" : "The OneDrive application secret. Required when `refreshToken` is set.",
"example" : "client-secret",
"secret" : true
}, {
"name" : "token",
"type" : "STRING",
"required" : false,
"description" : "An access token.",
"longDescription" : "A OneDrive OAuth2 token.\n\nWhen set, `refreshToken`, `clientId` and `clientSecret` are not required. It can be useful for testing, or if your application handles refreshing tokens.",
"secret" : true
}, {
"name" : "refreshToken",
"type" : "STRING",
"required" : false,
"description" : "A refresh token.",
"longDescription" : "An OAuth2 refresh token.",
"example" : "fdb8fdbecf1d03ce5e6125c067733c0d51de209c",
"secret" : true
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "SUPPORTED",
"namedQueries" : "NOT_IMPLEMENTED",
"entityScope" : "SUPPORTED",
"translationScope" : "NOT_AVAILABLE",
"versionScope" : "SUPPORTED",
"metadataScope" : "NOT_AVAILABLE",
"rpc" : "SUPPORTED",
"search" : "NOT_IMPLEMENTED",
"pagination" : "NOT_IMPLEMENTED"
}
}, {
"configurationType" : "Opentext",
"description" : "OpenText Content Server provides the core set of tools you need to capture, process and manage unstructured content across your organization including document management, workflow, search and information retrieval services, all tightly integrated into a platform that is easily customized and extended.",
"config" : [ {
"name" : "baseUrl",
"type" : "URL",
"required" : true,
"description" : "The URL of the OpenText Content Server.",
"longDescription" : "The full URL of the OpenText Content Server API extension: server, port and the path to the API root.",
"example" : "http://otcs.xillio.com:8080/otcs/cs.exe",
"secret" : false
}, {
"name" : "username",
"type" : "STRING",
"required" : true,
"description" : "The username of an account.",
"longDescription" : "The username of an account on OpenText.",
"example" : "username",
"secret" : false
}, {
"name" : "password",
"type" : "STRING",
"required" : true,
"description" : "The password of the account.",
"longDescription" : "The password of the account.",
"example" : "password",
"secret" : true
}, {
"name" : "rootNode",
"type" : "NUMBER",
"required" : false,
"description" : "The id of the root node.",
"longDescription" : "The id of the root node.",
"example" : "NO_EXAMPLE",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : 2000
}
}, {
"name" : "maxAuthAttempts",
"type" : "NUMBER",
"required" : false,
"description" : "The number of attempts to get an authentication ticket from Opentext Content Server.",
"longDescription" : "The number of attempts to get an authentication ticket from Opentext Content Server.",
"example" : "NO_EXAMPLE",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : 3
}
}, {
"name" : "retryAuthAfter",
"type" : "NUMBER",
"required" : false,
"description" : "Base number of seconds to wait between the first and second authentication attempt. This will be doubled for every following attempt.",
"longDescription" : "Base number of seconds to wait between the first and second authentication attempt. This will be doubled for every following attempt.",
"example" : "NO_EXAMPLE",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : 2
}
}, {
"name" : "ticket",
"type" : "STRING",
"required" : false,
"description" : "OpenText Content Server authentication ticket. Can be left empty when creating or updating a configuration.",
"longDescription" : "OpenText Content Server authentication ticket.",
"secret" : true
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "NOT_IMPLEMENTED",
"namedQueries" : "SUPPORTED",
"entityScope" : "SUPPORTED",
"translationScope" : "NOT_AVAILABLE",
"versionScope" : "SUPPORTED",
"metadataScope" : "SUPPORTED",
"rpc" : "SUPPORTED",
"search" : "SUPPORTED",
"pagination" : "SUPPORTED"
}
}, {
"configurationType" : "S3",
"description" : "S3 is a storage service offered by Amazon and other vendors. It stands for simple storage service and provides cloud storage for various types of web development applications.",
"config" : [ {
"name" : "baseUrl",
"type" : "URL",
"required" : true,
"description" : "The URL of the S3 API. This includes the bucket as sub-domain.",
"longDescription" : "The base URL to the target bucket. It _must_ include the bucket name.",
"example" : "https://mybucket.s3.amazonaws.com",
"secret" : false
}, {
"name" : "username",
"type" : "STRING",
"required" : true,
"description" : "The Access Key id to sign the S3 requests.",
"longDescription" : "The access key id to use for authentication.",
"example" : "AKIAIOSFODNN7EXAMPLE",
"secret" : true
}, {
"name" : "password",
"type" : "STRING",
"required" : true,
"description" : "The Secret Access Key to sign the S3 requests.",
"longDescription" : "The secret access key to use for authentication.",
"example" : "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"secret" : true
}, {
"name" : "region",
"type" : "STRING",
"required" : false,
"description" : "The region of the S3 instance.",
"longDescription" : "The region in which this bucket resides. Required for AWS S3 instances.",
"example" : "eu-central-1",
"secret" : false
}, {
"name" : "delimiter",
"type" : "STRING",
"required" : false,
"description" : "The delimiter used in your S3 bucket.",
"longDescription" : "The delimiter for traversing the bucket. See <<s3-hierarchy>>.",
"example" : "NO_EXAMPLE",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : "/"
}
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "NOT_IMPLEMENTED",
"contentTypeDiscovery" : "NOT_IMPLEMENTED",
"namedQueries" : "NOT_IMPLEMENTED",
"entityScope" : "SUPPORTED",
"translationScope" : "NOT_AVAILABLE",
"versionScope" : "NOT_IMPLEMENTED",
"metadataScope" : "NOT_IMPLEMENTED",
"rpc" : "SUPPORTED",
"search" : "NOT_IMPLEMENTED",
"pagination" : "NOT_IMPLEMENTED"
}
}, {
"configurationType" : "Salesforce",
"description" : "Salesforce Knowledge is part of complex cloud-based CRM solution.",
"config" : [ {
"name" : "baseUrl",
"type" : "URL",
"required" : true,
"description" : "The address of your Salesforce server.",
"longDescription" : "The base URL of the Salesforce API.",
"example" : "https://eu26.salesforce.com",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : "https://eu26.salesforce.com"
}
}, {
"name" : "refreshToken",
"type" : "STRING",
"required" : false,
"description" : "A refresh token to obtain access tokens with.",
"longDescription" : "An OAuth2 refresh token.",
"example" : "5Axc861F1.ndOFuBX057HR38ot4A7419...",
"secret" : true
}, {
"name" : "clientId",
"type" : "STRING",
"required" : false,
"description" : "Application identifier for refresh token authorization flow.",
"longDescription" : "The client id. Required when `refreshToken` is set.",
"example" : "3MFG96_7YM2sI9wTgZjGhoQXR6WBX35X...",
"secret" : false
}, {
"name" : "clientSecret",
"type" : "STRING",
"required" : false,
"description" : "Application secret for refresh token authorization flow.",
"longDescription" : "The client secret. Required when `refreshToken` is set.",
"example" : "FB5AE94E81B62A80692F4D9CUR63M890...",
"secret" : true
}, {
"name" : "token",
"type" : "STRING",
"required" : false,
"description" : "The token that is used for authenticating requests with Salesforce.",
"longDescription" : "An OAuth2 token.\n\nWhen set, `refreshToken`, `clientId` and `clientSecret` are not required. It can be useful for testing, or if your application handles refreshing tokens.",
"example" : "00A4p000000OtwS!AQNEPJgHxpEq9YXP...",
"secret" : true
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "NOT_IMPLEMENTED",
"namedQueries" : "NOT_IMPLEMENTED",
"entityScope" : "SUPPORTED",
"translationScope" : "SUPPORTED",
"versionScope" : "NOT_AVAILABLE",
"metadataScope" : "NOT_IMPLEMENTED",
"rpc" : "SUPPORTED",
"search" : "NOT_IMPLEMENTED",
"pagination" : "NOT_IMPLEMENTED"
}
}, {
"configurationType" : "SharePoint",
"description" : "SharePoint is web-based, collaborative platform that integrates with Microsoft Office.",
"config" : [ {
"name" : "baseUrl",
"type" : "URL",
"required" : true,
"description" : "The URL of the SharePoint Online site.",
"longDescription" : "The base URL of the SharePoint instance.",
"example" : "https://your-company.sharepoint.com",
"secret" : false
}, {
"name" : "authUrl",
"type" : "URL",
"required" : false,
"description" : "The URL of the Microsoft authentication endpoint for the SharePoint REST API.",
"longDescription" : "The URL of the Microsoft authentication endpoint.",
"example" : "https://login.microsoftonline.com/extSTS.srf",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : "https://login.microsoftonline.com/extSTS.srf"
}
}, {
"name" : "username",
"type" : "STRING",
"required" : true,
"description" : "The username of an account.",
"longDescription" : "The username of an account on SharePoint.",
"example" : "username",
"secret" : false
}, {
"name" : "password",
"type" : "STRING",
"required" : true,
"description" : "The password of the account.",
"longDescription" : "The password of the account.",
"example" : "password",
"secret" : true
}, {
"name" : "domain",
"type" : "STRING",
"required" : false,
"description" : "The MS Windows Domain for SharePoint On-Premises only.",
"longDescription" : "Windows NT Domain name, for SharePoint On-Premises only.",
"secret" : false
}, {
"name" : "site",
"type" : "STRING",
"required" : true,
"description" : "The site to which to connect.",
"longDescription" : "Site URL part which usually takes one of 2 forms:\n\"sites/MySite\" or just \"MySite\"",
"example" : "MySite",
"secret" : false
}, {
"name" : "version",
"type" : "STRING",
"required" : false,
"description" : "The version of Sharepoint On-Premise to connect to.",
"longDescription" : "The version of SharePoint instance. Supported values: 2013, 2016. Default value is 2016.",
"example" : "2016",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : "2016"
}
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "SUPPORTED",
"namedQueries" : "NOT_IMPLEMENTED",
"entityScope" : "SUPPORTED",
"translationScope" : "NOT_AVAILABLE",
"versionScope" : "SUPPORTED",
"metadataScope" : "SUPPORTED",
"rpc" : "SUPPORTED",
"search" : "NOT_IMPLEMENTED",
"pagination" : "NOT_IMPLEMENTED"
}
}, {
"configurationType" : "SharePointV2",
"description" : "SharePoint is web-based, collaborative platform that integrates with Microsoft Office.",
"config" : [ {
"name" : "baseUrl",
"type" : "URL",
"required" : true,
"description" : "The URL of the SharePoint Online site",
"longDescription" : "The base URL of the SharePoint instance.",
"example" : "https://your-company.sharepoint.com",
"secret" : false
}, {
"name" : "authUrl",
"type" : "URL",
"required" : false,
"description" : "The URL of the Microsoft authentication endpoint for the SharePoint REST API",
"longDescription" : "The URL of the Microsoft authentication endpoint.",
"example" : "https://accounts.accesscontrol.windows.net",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : "https://accounts.accesscontrol.windows.net"
}
}, {
"name" : "clientId",
"type" : "STRING",
"required" : true,
"description" : "Client Id of registered SharePoint Add-In",
"longDescription" : "The SharePoint app client-id to access the API.",
"example" : "91391ad5-f8b4-4007-8e98-e2e695c0bcb2",
"secret" : false
}, {
"name" : "clientSecret",
"type" : "STRING",
"required" : true,
"description" : "Client Secret registered SharePoint Add-In",
"longDescription" : "The SharePoint app client secret to access the API.",
"example" : "mQ1eApeD251QJkNBodWRGYCES2PnEhaq1+YoM0DHrw8=",
"secret" : true
}, {
"name" : "tenantId",
"type" : "STRING",
"required" : true,
"description" : "Id of your SharePoint tenant",
"longDescription" : "ID of the SharePoint tenant.",
"example" : "f15805d7-484f-456f-b28d-5f3afae0f44b",
"secret" : false
}, {
"name" : "site",
"type" : "STRING",
"required" : true,
"description" : "The site to which to connect",
"longDescription" : "Site URL part which usually takes one of 2 forms:\n\"sites/MySite\" or just \"MySite\"",
"example" : "MySite",
"secret" : false
}, {
"name" : "version",
"type" : "STRING",
"required" : false,
"description" : "The version of Sharepoint to connect to",
"longDescription" : "The version of SharePoint instance. Supported values: 2013, 2016. Default value is 2016.",
"example" : "2016",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : "online"
}
}, {
"name" : "resourceId",
"type" : "STRING",
"required" : true,
"description" : "Resource information identifying Microsoft application. For SharePoint Online, use the default value",
"longDescription" : "Resource information identifying Microsoft application.",
"example" : "00000003-0000-0ff1-ce00-000000000000",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : "00000003-0000-0ff1-ce00-000000000000"
}
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "SUPPORTED",
"namedQueries" : "NOT_IMPLEMENTED",
"entityScope" : "SUPPORTED",
"translationScope" : "NOT_AVAILABLE",
"versionScope" : "SUPPORTED",
"metadataScope" : "SUPPORTED",
"rpc" : "SUPPORTED",
"search" : "NOT_IMPLEMENTED",
"pagination" : "NOT_IMPLEMENTED"
}
}, {
"configurationType" : "Sitecore",
"description" : "Sitecore is a CMS with additional marketing functionality that analyses customer data from multiple sources and makes it possible to show custom content.",
"config" : [ {
"name" : "baseUrl",
"type" : "URL",
"required" : true,
"description" : "The URL of the Sitecore target system.",
"longDescription" : "The base URL of the Sitecore instance.",
"example" : "https://sitecore.mydomain.com",
"secret" : false
}, {
"name" : "username",
"type" : "STRING",
"required" : true,
"description" : "The username of an account.",
"longDescription" : "The username of an account on Sitecore.",
"example" : "username",
"secret" : false
}, {
"name" : "password",
"type" : "STRING",
"required" : true,
"description" : "The password of the account.",
"longDescription" : "The password of the account.",
"example" : "password",
"secret" : true
}, {
"name" : "database",
"type" : "STRING",
"required" : true,
"description" : "The database of the Sitecore target system.",
"longDescription" : "Database on the Sitecore target system.\n\nValid values are `core`, `master` or `web`.",
"example" : "master",
"secret" : false
}, {
"name" : "domain",
"type" : "STRING",
"required" : true,
"description" : "The domain to which to connect.",
"longDescription" : "The domain to which to connect.",
"example" : "sitecore",
"secret" : false
}, {
"name" : "ignoreExpiryDateOnCookies",
"type" : "BOOLEAN",
"required" : false,
"description" : "Ignore the expiry date on cookies.",
"longDescription" : "Enable this setting to ignore the expiry date on cookies.\n\nWARNING: For development only. Omit in a production environment.",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : false
}
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "NOT_IMPLEMENTED",
"namedQueries" : "NOT_IMPLEMENTED",
"entityScope" : "SUPPORTED",
"translationScope" : "SUPPORTED",
"versionScope" : "SUPPORTED",
"metadataScope" : "NOT_IMPLEMENTED",
"rpc" : "SUPPORTED",
"search" : "NOT_IMPLEMENTED",
"pagination" : "NOT_IMPLEMENTED"
}
}, {
"configurationType" : "Trim",
"description" : "Automate secure content and records management, from creation to disposal, to regain control of your assets and mitigate risk. Previously known as HP Content Manager and HP Trim.",
"config" : [ {
"name" : "baseUrl",
"type" : "URL",
"required" : true,
"description" : "The URL of the TRIM system Service API.",
"longDescription" : "The absolute URL to the TRIM Service API.",
"example" : "http://trim.xillio.com/HPECMServiceAPI/",
"secret" : false
}, {
"name" : "username",
"type" : "STRING",
"required" : true,
"description" : "The username of an account.",
"longDescription" : "The username of an account on TRIM.",
"example" : "username",
"secret" : false
}, {
"name" : "password",
"type" : "STRING",
"required" : true,
"description" : "The password of the account.",
"longDescription" : "The password of the account.",
"example" : "password",
"secret" : true
}, {
"name" : "rootQuery",
"type" : "STRING",
"required" : false,
"description" : "Defines the set of records in the root for this connector.",
"longDescription" : "A TRIM query string, see <<Root Query>>.",
"example" : "NO_EXAMPLE",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : "*"
}
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "NOT_IMPLEMENTED",
"contentTypeDiscovery" : "NOT_IMPLEMENTED",
"namedQueries" : "SUPPORTED",
"entityScope" : "SUPPORTED",
"translationScope" : "NOT_AVAILABLE",
"versionScope" : "SUPPORTED",
"metadataScope" : "NOT_IMPLEMENTED",
"rpc" : "SUPPORTED",
"search" : "NOT_IMPLEMENTED",
"pagination" : "NOT_IMPLEMENTED"
}
}, {
"configurationType" : "WordPress",
"description" : "WordPress is a free and open-source content management system (CMS). Features include a plugin architecture and a template system.",
"config" : [ {
"name" : "baseUrl",
"type" : "URL",
"required" : true,
"description" : "The URL of the WordPress site.",
"longDescription" : "The URL of the WordPress site.",
"example" : "https://demo.wp-api.org/",
"secret" : false
}, {
"name" : "username",
"type" : "STRING",
"required" : true,
"description" : "The username of an account.",
"longDescription" : "The username of an account on WordPress (with Administrator privileges).",
"example" : "username",
"secret" : false
}, {
"name" : "password",
"type" : "STRING",
"required" : true,
"description" : "The password of the account.",
"longDescription" : "The password of the account, or the generated application password, depending on the authentication type.",
"example" : "password",
"secret" : true
}, {
"name" : "token",
"type" : "STRING",
"required" : false,
"description" : "An access token.",
"longDescription" : "A WordPress OAuth2 token.\n\nOptional if logging in with a `username` and `password` combination.",
"secret" : true
}, {
"name" : "authenticationType",
"type" : "STRING",
"required" : true,
"description" : "The authentication type to use.",
"longDescription" : "Specifies which authentication type the connector should use. Valid options are `basic` and `jwt`.",
"example" : "NO_EXAMPLE",
"secret" : false,
"default" : {
"mustDefaultWith" : [ ],
"value" : "jwt"
}
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "NOT_IMPLEMENTED",
"namedQueries" : "NOT_IMPLEMENTED",
"entityScope" : "SUPPORTED",
"translationScope" : "SUPPORTED",
"versionScope" : "SUPPORTED",
"metadataScope" : "NOT_IMPLEMENTED",
"rpc" : "SUPPORTED",
"search" : "NOT_IMPLEMENTED",
"pagination" : "NOT_IMPLEMENTED"
}
}, {
"configurationType" : "Zendesk",
"description" : "Zendesk Guide is a smart knowledge base system for better self-service and empowered agents.",
"config" : [ {
"name" : "baseUrl",
"type" : "URL",
"required" : true,
"description" : "The URL of the Zendesk server.",
"longDescription" : "The URL of the target Zendesk site.",
"example" : "https://yoursite.zendesk.com",
"secret" : false
}, {
"name" : "username",
"type" : "STRING",
"required" : false,
"description" : "The username of an account, or the username and \"/token\".",
"longDescription" : "Depending on your authentication method, either of:\n\n - The email you are using to log in to the Zendesk web interface\n - The concatenation of your username and `/token`",
"example" : "your@email.com",
"secret" : false
}, {
"name" : "password",
"type" : "STRING",
"required" : false,
"description" : "The password of the account, or the API token.",
"longDescription" : "Depending on your authentication method, either of:\n\n - The password you are using to log in to the Zendesk web interface\n - The API token assigned to the selected user",
"example" : "password",
"secret" : true
}, {
"name" : "token",
"type" : "STRING",
"required" : false,
"description" : "An access token.",
"longDescription" : "A Zendesk OAuth2 token.\n\nShould not be provided if `username` and `password` are provided.",
"secret" : true
}, {
"name" : "permissionGroupId",
"type" : "NUMBER",
"required" : false,
"description" : "The id of the permission group that is used when creating articles.",
"longDescription" : "_Optional._ +\nThe id of the management permission group that is used when creating articles.",
"example" : "2102353",
"secret" : false
} ],
"features" : {
"read" : "SUPPORTED",
"write" : "SUPPORTED",
"contentTypeDiscovery" : "NOT_IMPLEMENTED",
"namedQueries" : "NOT_IMPLEMENTED",
"entityScope" : "SUPPORTED",
"translationScope" : "SUPPORTED",
"versionScope" : "NOT_AVAILABLE",
"metadataScope" : "NOT_IMPLEMENTED",
"rpc" : "SUPPORTED",
"search" : "NOT_IMPLEMENTED",
"pagination" : "NOT_IMPLEMENTED"
}
} ]2.14. /system
2.14.1. Ping
Ping the Xillio API. This can be used to check the health of the system and your tenant. If the tenant could not be found, a 404 response is returned.
GET /v2/system/ping ------ HTTP/1.1 200 OK Content-Type: application/json
$ curl 'https://demo-tenant.xill.io/v2/system/ping' -i -X GET| Path | Type | Description |
|---|---|---|
|
|
The name of the current tenant. |
|
|
The current server time. |
HTTP/1.1 200 OK
{
"tenant" : "demo-tenant",
"serverTime" : "2024-03-14T08:17:04.969Z"
}2.14.2. Version
Receive the version information of the Xillio API.
GET /v2/system/version ------ HTTP/1.1 200 OK Content-Type: application/json
$ curl 'https://demo-tenant.xill.io/v2/system/version' -i -X GET| Path | Type | Description |
|---|---|---|
|
|
The name of the software. |
|
|
The current software version. |
HTTP/1.1 200 OK
{
"softwareName" : "Xillio API",
"softwareVersion" : "testing"
}2.15. /rpc
| For documentation of the specific RPC methods, see the RPC section of the connector documentation. |
| New RPC methods can be created on request. Please contact support to be informed about the possibilities. |
2.15.1. Get all RPC methods
List all RPC methods for the given configuration.
This endpoint requires an access_token for scope rpc for a user with role RPC_USER.
|
GET /v2/rpc/{configurationId}
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
$ curl 'https://demo-tenant.xill.io/v2/rpc/9415fa1d561944a886a992db037cf447' -i -X GET \
-H 'Authorization: Bearer <<YOUR_TOKEN>>'| Path | Type | Description |
|---|---|---|
|
|
The type of the configuration exposing the RPC methods |
|
|
An array of all the RPC methods. |
|
|
The namespace of the RPC method. |
|
|
The name of the RPC method. |
|
|
The URL on which the RPC method can be invoked. |
HTTP/1.1 200 OK
{
"configurationType" : "FileSystem",
"handlers" : [ {
"namespace" : "files",
"method" : "attributes",
"url" : "https://demo-tenant.xill.io/v2/rpc/9415fa1d561944a886a992db037cf447/files/attributes"
} ]
}2.15.2. Invoke an RPC method
RPC methods can be invoked using either a GET or a POST request.
The input for an RPC method can be supplied either through query parameters or the request body.
When using a request body, the body should be a JSON object containing fields for each input parameter, e.g.: { "path": "/some/path" }.
When using query parameters, the parameter key must match an argument name of the RPC method, e.g.: path=%2Fsome%2Fpath.
Query parameter values have precedence over values in the request body.
RPC methods can have optional and mandatory parameters. If no value is supplied for an optional parameter, a default value is used. If a mandatory value is not supplied, an error will be returned.
The response body is the result of the invoked method serialized to JSON.
This is a non-unified value.
If no result is returned, the response code will be 204 - No Content without a response body.
Passthrough Authorization
This endpoint supports Passthrough-Authorization. Read the Create a New Configuration endpoint documentation to find out how to use this mechanism.
This endpoint requires an access_token for scope rpc for a user with role RPC_USER.
|
POST /v2/rpc/{configurationId}/{namespace}/{method}
------
HTTP/1.1 200 OK
Content-Type: application/json
| Parameter | Description |
|---|---|
|
The id of a configured repository. |
|
The namespace of the to be invoked RPC method. |
|
The name of the method to invoke. |
$ curl 'https://demo-tenant.xill.io/v2/rpc/faf7ada3af1a46ca89dfbc52e7924b88/files/attributes' -i -X POST \
-H 'Authorization: Bearer <<YOUR_TOKEN>>' \
-H 'Content-Type: application/json' \
-d '{
"path" : "./file.txt"
}'HTTP/1.1 200 OK
{
"attributes" : {
"lastAccessTime" : "2024-03-14T08:17:01.079883Z",
"lastModifiedTime" : "2024-03-14T08:17:01.079883Z",
"size" : "12",
"creationTime" : "2024-03-14T08:17:01.079883Z",
"isSymbolicLink" : "false",
"isRegularFile" : "true",
"fileKey" : "(dev=53,ino=2977814)",
"isOther" : "false",
"isDirectory" : "false"
}
}2.16. Possible Endpoints Errors
If an error occurs while handling a request, it will be returned as the response instead. All errors adhere to the following structure:
| Path | Type | Description |
|---|---|---|
|
|
The id of the error. This id can be used in support requests. |
|
|
A contextual message that describes the cause of this error. |
|
|
A more general error message. |
|
|
The http status code. |
|
|
The date this exception occurred. |
|
|
The type of error that occurred in the backend. |
|
|
The request URI that caused this error. |
|
|
The parameters that were passed to this request. |
The most common errors with their respective responses are:
2.16.1. No Such Entity
This error occurs when the requested entity could not be found. This error also occurs when the URL does not match the format a connector expected, for example with an nonexistent collection in a REST based system.
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
{
"errorId" : "47262ac0-25a9-442e-8082-428074472a22",
"message" : "No entity was found at xdip://59e4b5a7857aba0005a2822a/non/existing/entity",
"error" : "Not Found",
"status" : 404,
"timestamp" : "2024-03-14T08:16:42.810Z",
"errorType" : "NoSuchEntity",
"parameters" : { }
}2.16.2. No Such Configuration
This error occurs when the requested configuration could not be found.
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
{
"errorId" : "71a2805d-2932-4233-bab2-c98ee0e11f9d",
"message" : "No configuration was found for '59e4b5a7857aba0005a28228'",
"error" : "Not Found",
"status" : 404,
"timestamp" : "2024-03-14T08:16:42.806Z",
"errorType" : "NoSuchConfiguration",
"parameters" : { }
}2.16.3. No Such Content Script
This error occurs when the requested content script could not be found.
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
{
"errorId" : "6dda6a50-9d7c-43f5-a6da-69c33aa764c8",
"message" : "No content script was found for '59e4b5a7853aba0005a2822a'",
"error" : "Not Found",
"status" : 404,
"timestamp" : "2024-03-14T08:16:42.808Z",
"errorType" : "NoSuchContentScript",
"parameters" : { }
}2.16.4. Content Script Already Exists
This error occurs when a content script is manipulated or created which conflicts with an existing content script on the configuration. A configuration cannot have two content scripts that share the same mimetype and type.
HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8
{
"errorId" : "7b8c60b6-8348-4d89-941f-2488c5218db0",
"message" : "Supplied content script already exists: A content script with the mimeType 'application/xml' and type 'READ' on configuration with id '59e4b5a7353aba0005a2822a' already exists.",
"error" : "Conflict",
"status" : 409,
"timestamp" : "2024-03-14T08:16:42.751Z",
"errorType" : "ContentScriptAlreadyExists",
"parameters" : { }
}2.16.5. No Such Query Configuration
This error occurs when the requested named query configuration could not be found.
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
{
"errorId" : "6b153ff3-be69-47b5-9b03-32692c921915",
"message" : "No named query was found for 'queryName' on configuration '59e4b5a7353aba0005a2822a'",
"error" : "Not Found",
"status" : 404,
"timestamp" : "2024-03-14T08:16:42.814Z",
"errorType" : "NoSuchQueryConfiguration",
"parameters" : { }
}2.16.6. No Such Handler
This error occurs when the requested RPC method could not be found.
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
{
"errorId" : "6988f32a-084b-4e66-8355-e11727cfdb2f",
"message" : "No method was found for namespace/non-existing-method",
"error" : "Not Found",
"status" : 404,
"timestamp" : "2024-03-14T08:16:42.812Z",
"errorType" : "NoSuchHandler",
"parameters" : { }
}2.16.7. Query Configuration Already Exists
This error occurs when creating a named query with a name which is already used by another query in the same configuration. A configuration cannot have two named queries sharing the same name.
HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8
{
"errorId" : "13d01ef9-8188-4252-a020-172d1f042091",
"message" : "The named query configuration 'queryName' on configuration with id '59e4b5a7353aba0005a2822a' already exists.",
"error" : "Conflict",
"status" : 409,
"timestamp" : "2024-03-14T08:16:42.825Z",
"errorType" : "QueryConfigurationAlreadyExists",
"parameters" : { }
}2.16.8. Invalid Template Variable
This error occurs when a named query template uses a variable name which is not prefixed correctly or is empty.
See Named Queries.
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"errorId" : "d7dd7194-e7be-4777-af22-c75a8cb1d6f6",
"message" : "All template variables must be not empty and prefixed with 'q_'. Invalid variable names: variable",
"error" : "Bad Request",
"status" : 400,
"timestamp" : "2024-03-14T08:16:42.780Z",
"errorType" : "InvalidTemplateVariable",
"parameters" : { }
}2.16.9. Invalid Query Variable
This error occurs when executing a query and is caused by a violation of any of the following constraints:
-
When executing a query without specifying all template variables as URL parameters (missing variable)
-
When executing a query specifying more URL parameters than the template contains (unused variable)
-
When a query variable is assigned more than one value
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"errorId" : "bea2b810-2adf-4278-be7b-4c970316ca3b",
"message" : "Invalid query variables. Missing: [q_my-missing-variable]. Unused: [q_my-unused-variable]",
"error" : "Bad Request",
"status" : 400,
"timestamp" : "2024-03-14T08:16:42.775Z",
"errorType" : "InvalidQueryVariable",
"parameters" : { }
}2.16.10. Invalid Query
This error occurs when the query template, or the query template after the substitution of variables, is not a valid query for the target system, either syntactically or semantically.
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"errorId" : "af78d3b2-63b6-495d-b974-ece4b268247b",
"message" : "The query could not be parsed by the target system: The query is not valid",
"error" : "Bad Request",
"status" : 400,
"timestamp" : "2024-03-14T08:16:42.773Z",
"errorType" : "InvalidQuery",
"parameters" : { }
}2.16.11. Invalid Configuration
This error occurs when creating or updating a configuration and the input is invalid.
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"errorId" : "3bbe9afa-9b76-4845-b921-19653d83bac2",
"message" : "Missing required field 'rootPath'",
"error" : "Bad Request",
"status" : 400,
"timestamp" : "2024-03-14T08:16:42.771Z",
"errorType" : "InvalidConfiguration",
"parameters" : { }
}2.16.12. Configuration Already Exists
This error occurs when creating a configuration with an id that already exists
HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8
{
"errorId" : "7a935d9b-632b-40b8-a1fa-7c38df83da47",
"message" : "The configuration id 'customConfigurationId' already exists",
"error" : "Conflict",
"status" : 409,
"timestamp" : "2024-03-14T08:16:42.747Z",
"errorType" : "ConfigurationAlreadyExists",
"parameters" : { }
}2.16.13. No Such User
This error occurs when the requested user could not be found.
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
{
"errorId" : "8f563f25-2fed-48e0-81a0-efa928d81747",
"message" : "No user with id 'myUsername' was found in tenant 'myTenant'",
"error" : "Not Found",
"status" : 404,
"timestamp" : "2024-03-14T08:16:42.821Z",
"errorType" : "NoSuchUser",
"parameters" : { }
}2.16.14. Invalid User
This error occurs when creating or updating a user and the input is invalid.
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"errorId" : "e70884f4-eee8-404f-8de8-a8d1d5ee9917",
"message" : "Supplied user was not valid: A user with the username 'myUsername' already exists.",
"error" : "Bad Request",
"status" : 400,
"timestamp" : "2024-03-14T08:16:42.784Z",
"errorType" : "InvalidUserArgument",
"parameters" : { }
}2.16.15. Entity Already Exists
This error occurs when doing a manipulative operation on a specific entity where this operation conflicts with the underlying system since there is already something in that place. For example, when moving an existing entity to a location where another entity already exists.
HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8
{
"errorId" : "78dca566-e37b-405a-9af8-df0e93a55d7c",
"message" : "'xdip://59e4b5a6857aba0005a28227/existing/entity' already exists.",
"error" : "Conflict",
"status" : 409,
"timestamp" : "2024-03-14T08:16:42.765Z",
"errorType" : "EntityAlreadyExists",
"parameters" : { }
}2.16.16. Missing Decorator
This error occurs when performing an operation which requires a certain decorator and the decorator is not present.
For example, during an attempt to create a new entity but do not provide the name decorator.
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"errorId" : "11e21e7c-8324-4d4c-abff-0f865844f28d",
"message" : "Missing required decorator: parent",
"error" : "Bad Request",
"status" : 400,
"timestamp" : "2024-03-14T08:16:42.801Z",
"errorType" : "MissingDecorator",
"parameters" : { }
}2.16.17. No Binary Content
This error occurs when requesting or updating the contents of an entity which is not capable of containing contents. If an entity is capable of containing contents but it does not, this error does not occur.
HTTP/1.1 405 Method Not Allowed
Content-Type: application/json;charset=UTF-8
{
"errorId" : "a81b522c-4762-4286-88f5-3f8278dc257b",
"message" : "No content found at xdip://59e4b5a6857aba0005a28227/New%20Folder",
"error" : "Method Not Allowed",
"status" : 405,
"timestamp" : "2024-03-14T08:16:42.804Z",
"errorType" : "NoBinaryContent",
"parameters" : { }
}2.16.18. Content Script Failed
This error occurs when the content script has reached a timeout or has encountered a compile, runtime or user thrown error.
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
{
"errorId" : "24ecf792-b5c9-4dd4-b458-9731ebaa4b71",
"message" : "Something went wrong while running the content script.",
"error" : "Unprocessable Entity",
"status" : 422,
"timestamp" : "2024-03-14T08:16:42.753Z",
"errorType" : "ContentScriptFailed",
"parameters" : { }
}2.16.19. Operation Not Allowed
This error occurs when performing an operation that cannot complete due to limitations.
For example, moving an entity into another entity which cannot have children (and does not have the container decorator).
HTTP/1.1 405 Method Not Allowed
Content-Type: application/json;charset=UTF-8
{
"errorId" : "849d6ec1-aa29-4290-b722-056d26227cfc",
"message" : "Files cannot contain other files",
"error" : "Method Not Allowed",
"status" : 405,
"timestamp" : "2024-03-14T08:16:42.823Z",
"errorType" : "OperationNotAllowed",
"parameters" : { }
}2.16.20. Authorization Failed
This error occurs when performing an action for which you are not authorized by the target system, or when the configuration contains invalid credentials.
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
{
"errorId" : "042ffe39-a3cd-444f-af69-6b7f7532bb29",
"message" : "You are not allowed to create files in this folder",
"error" : "Forbidden",
"status" : 403,
"timestamp" : "2024-03-14T08:16:42.745Z",
"errorType" : "AuthorizationFailed",
"parameters" : { }
}2.16.21. Host Not Reached
This error occurs when the API is not able to communicate with the host which was set in the configuration.
HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8
{
"errorId" : "800432f1-37f7-4998-9e35-c91a60289928",
"message" : "Could not find host at https://hostisnotfound.com",
"error" : "Service Unavailable",
"status" : 503,
"timestamp" : "2024-03-14T08:16:42.767Z",
"errorType" : "HostNotReached",
"parameters" : { }
}2.16.22. Unauthorized Configuration Type
This error occurs when performing a create or update on a configuration with an unauthorized configuration type.
All the allowed configuration types of a tenant can be checked by calling the /v2/tenant endpoint.
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
{
"errorId" : "732f7e8a-e9e8-452e-b392-a06101f40330",
"message" : "Configuration type 'BitBucket' is not available for your tenant.",
"error" : "Forbidden",
"status" : 403,
"timestamp" : "2024-03-14T08:16:42.830Z",
"errorType" : "UnauthorizedConfigurationType",
"parameters" : { }
}2.16.23. Unsupported Content Type
This error occurs when performing a create or update operation using an unsupported value in the kind or
contentType.systemName fields.
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"errorId" : "bf35725f-daec-4dda-93f1-1442bdec8179",
"message" : "application/vnd.google-apps.folder is not supported by Episerver",
"error" : "Bad Request",
"status" : 400,
"timestamp" : "2024-03-14T08:16:42.832Z",
"errorType" : "UnsupportedContentType",
"parameters" : { }
}2.16.24. Quota Exceeded
This error occurs when the quota or usage limit of the target system has been exceeded. Most systems impose flood prevention mechanisms such as api rate-limits.
This error does not occur when the Xillio API usage limits are exceeded as it only applies to the target systems.
If supported by the target system, this error will include the Retry-After header to indicate the time after which this request can be retried.
HTTP/1.1 429 Too Many Requests
Content-Type: application/json;charset=UTF-8
{
"errorId" : "167c053b-957f-444f-9c6a-227ccaef6a80",
"message" : "Rate Limit exceeded Please retry after 42 seconds.",
"error" : "Too Many Requests",
"status" : 429,
"timestamp" : "2024-03-14T08:16:42.827Z",
"errorType" : "QuotaExceeded",
"parameters" : { }
}2.16.25. Insufficient Storage
This error occurs when the storage limit on the target system is exceeded and no more space is available to perform a requested operation. This error is only thrown when supported by the target system.
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
{
"errorId" : "00c776bb-5ade-40d0-8a98-2cf680f04db0",
"message" : "The maximum storage quota has been reached.",
"error" : "Internal Server Error",
"status" : 500,
"timestamp" : "2024-03-14T08:16:42.769Z",
"errorType" : "InsufficientStorage",
"parameters" : { }
}2.16.26. Unauthorized
This error occurs when no valid authorization was done while accessing the API.
This error does not occur when Xillio API could not connect to a target system due to authentication issues.
HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8
{
"errorId" : "fd996fcc-86e4-43ed-ac85-d37ae7fd9377",
"message" : "You are not authenticated",
"error" : "Unauthorized",
"status" : 401,
"timestamp" : "2024-03-14T08:16:42.829Z",
"errorType" : "Unauthorized",
"parameters" : { }
}2.16.27. Access Denied
This error occurs when the scope of the current authentication does not match the allowed scopes of the called endpoint of this API.
HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8
{
"errorId" : "0219960f-9e7b-44aa-9237-546c3f8b379c",
"message" : "Access is denied",
"error" : "Forbidden",
"status" : 403,
"timestamp" : "2024-03-14T08:16:42.653Z",
"errorType" : "AccessDenied",
"parameters" : { }
}2.16.28. Misconfigured System
The target system has unmet preconditions, meaning the API cannot connect to it. Solve the problem in the error message and try again.
HTTP/1.1 503 Service Unavailable
Content-Type: application/json;charset=UTF-8
{
"errorId" : "55c4087f-bbad-46f3-a5bb-c9a53623d391",
"message" : "The target system has disabled the 'integrations api'. Please enable the 'integrations api' feature to connect.",
"error" : "Service Unavailable",
"status" : 503,
"timestamp" : "2024-03-14T08:16:42.794Z",
"errorType" : "MisconfiguredSystem",
"parameters" : { }
}2.16.29. Connector Operation Failed
This error occurs when an unknown error occurred while attempting to perform the requested operation.
HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8
{
"errorId" : "ff13277a-b129-4fad-af73-a9ede28aeab5",
"message" : "An internal server error occurred, please contact an administrator.",
"error" : "Internal Server Error",
"status" : 500,
"timestamp" : "2024-03-14T08:16:42.749Z",
"errorType" : "ConnectorOperationFailed",
"parameters" : { }
}2.16.30. No Such Tenant
This error occurs when the tenant you are using could not be found.
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
{
"errorId" : "07b025cf-686e-461b-b18f-45173e329093",
"message" : "No tenant with name 'my-tenant' was found",
"error" : "Not Found",
"status" : 404,
"timestamp" : "2024-03-14T08:16:42.819Z",
"errorType" : "NoSuchTenant",
"parameters" : { }
}2.16.31. Invalid XDIP
This error occurs when a request URL or reference URL does not match the XDIP constraints:
XDIP URLs must match the URL protocol with the following additions:
-
They must use the XDIP scheme
-
They cannot use fragment parameters
-
They cannot use user information
-
They cannot use port specifications
-
The first component (or configuration id) can only contain alphanumerics and dashes, but the id cannot start or end with a dash. The minimum length is 2.
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"errorId" : "d235faf9-d77a-4e06-b3f6-d7b5dd166548",
"message" : "Invalid XDIP URL 'xdip://3/'. Configuration ids can only contain alphanumerics and dashes, but the id cannot start or end with a dash. The minimum length is two.",
"error" : "Bad Request",
"status" : 400,
"timestamp" : "2024-03-14T08:16:42.787Z",
"errorType" : "InvalidXDIP",
"parameters" : { }
}2.16.32. Deprecated
This error occurs when creating configurations and other entities that have a preferred implementation somewhere else in the API.
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json;charset=UTF-8
{
"errorId" : "98b63af1-14d4-48ba-9c75-5b7815182222",
"message" : "The connector 'DeprecatedConnector' is deprecated. Please use 'NotDeprecatedConnector'",
"error" : "Unprocessable Entity",
"status" : 422,
"timestamp" : "2024-03-14T08:16:42.761Z",
"errorType" : "Deprecated",
"parameters" : { }
}2.16.33. No Such Scope
This error occurs when one of the provided scope names is invalid.
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
{
"errorId" : "684e98ea-a4da-4f2f-b482-18174edff407",
"message" : "Scope 'my:scope' is not valid. Valid scopes are: entity, reference, metadata. Valid relationship names in the 3-part form of <relationship>_<navigation>_<return type> are: path, version, translation",
"error" : "Bad Request",
"status" : 400,
"timestamp" : "2024-03-14T08:16:42.817Z",
"errorType" : "NoSuchScope",
"parameters" : { }
}3. Connectors
An overview of the current capabilities of the connectors can be found on: https://api.xill.io/connectors
Connector Descriptions
Connector descriptions start with the name of the connector, general information on the target system of the connector, and a short overview of supported target system versions.
| Connectors might work with unsupported target system versions, but their behavior could be unpredictable. |
Configuration
The Configuration section describes what needs to be done to configure the connector to work with your system.
This section includes at least a description of the configuration parameters and a minimal configuration example. In the table describing the fields, bold indicates that a field is mandatory, and italic indicates that the parameter has a default value, and can therefore be omitted.
Features and Limitations
The Features and Limitations section describes what can be expected from the connector. The connectors are intended to be as complete as possible, but in some cases the system just doesn’t support certain functionality or behaves slightly differently from what is expected.
Mappings
The Mappings section describes how data in the system is mapped to data in our internal model and potentially in which way it is converted. This section will have a table that looks like this, potentially with extra columns where needed:
| Decorator | Used By | Field in System | Description |
|---|---|---|---|
Decorator name |
Content types that use this decorator |
Field in the system |
Information on the mapping and/or conversion. |
3.1. AEM
Adobe Experience Manager brings your content management system (CMS) and digital asset management (DAM) together — in one place.
Version(s): we support AEM 6.4 and newer.
3.1.1. Configuration
The AEM connector connects to the AEM Content Repository Extreme (CRX) repository. The CRX repository can be viewed inside AEM through CRXDE Lite.
When configuring the AEM connector, the user referenced in the configuration needs at least jcr:read privileges on JCR nodes that should be exposed. For more information on AEM permissions and on how to set them up, please refer to the AEM documentation.
| Parameter | Description |
|---|---|
The base URL of the AEM host. |
|
The username of an account with permissions to access CRX. |
|
The password of an account with permissions to access CRX. |
|
The JCR workspace to access. Default: |
{
"configurationType": "Aem",
"config" : {
"baseUrl" : "https://aem.xillio.com:4502",
"username" : "username",
"password" : "password"
}
}3.1.2. Features and Limitations
-
This connector is read-only.
-
Only JCR nodes of type
nt:file,nt:folder,cq:Pageanddam:Assetare exposed. -
Both content fragments and regular assets are supported for nodes of type
dam:Asset. -
Only nodes of type
nt:folderandcq:Pagesupport thepathrelation. -
Contents of nodes of type
nt:folder,cq:Pageand content fragments (dam:Asset) are exposed as the JCR system view XML of theirjcr:contentchild node.
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|||
|
3.1.3. Mappings
| Decorator | Used By | Field in AEM | Description |
|---|---|---|---|
|
|
Whether the entity can have children according to the |
|
|
|
|
The primary JCR type of the JCR node corresponding to the entity. |
|
|
|
The date and time at which the JCR node corresponding to the entity was created. |
|
|
|
The username of the account used to create the JCR node corresponding to the entity. |
|
|
|
The asset description. |
|
|
Extracted from the JCR node name |
The file extension of the asset. |
|
|
Extracted from the JCR node name |
The file extension of the asset. |
|
|
|
The file size of the original rendition of the asset or the file. |
|
|
JCR node path |
The path of the JCR node corresponding to the entity. |
|
|
|
The sha1 hash of the original rendition of the asset. |
|
|
|
The language of the JCR node corresponding to the entity. |
|
|
|
The mime type of the original rendition of the asset. The XML mime type for all other entities, since their contents is returned as JCR system view XML. |
|
|
|
The date and time at which the JCR node corresponding to the entity was last modified. |
|
|
|
The username of the account used to last modify the JCR node corresponding to the entity. |
|
|
JCR node name |
The name of the JCR node corresponding to the entity. |
|
|
|
The title of the JCR node corresponding to the entity. |
|
|
The id of the entity corresponding to the parent JCR node. |
3.2. Bitbucket
This is the connector for the Bitbucket Cloud Service API. This system will be referred to as Bitbucket in the remainder of the documentation.
Version(s): version 2 of the API.
3.2.1. Configuration
The configuration for this connector consists of a URL to Bitbucket, user credentials and (optionally) an owner to define the children (repositories) of the root entity.
| The connector currently only supports HTTP basic authentication. |
| Parameter | Description |
|---|---|
The base URL of the Bitbucket v2 cloud service. Default: |
|
The username of an account on Bitbucket (not the email address). |
|
The password of the account. |
|
The owner for which to select repositories. When not provided, the connector will use the The repositories shown with this setting are only the ones owned by the owner, not the repositories to which the user has access to. |
{
"configurationType": "Bitbucket",
"config" : {
"username" : "username",
"password" : "password",
"owner" : "repository-owner"
}
}3.2.2. Features and Limitations
The children of the root elements are always of type Repository. The children of a Repository are always of type
Branch. The children of a Branch are of type Folder or File. The children of Folder are of type Folder or
File.
This connector has the following limitations:
-
Only basic authentication is supported using this connector.
-
Only read operations are allowed on repositories and branches.
-
Only read operations are allowed on the metadata of files and folders.
-
Due to the specific nature of the underlying git system, it is not possible to delete folders. In fact: in Bitbucket a folder does not exist, it only manifests itself when a file is created with a path pointing to that folder. Recursively deleting a folder would have huge impact on the performance of the connector, as it would result in a lot of calls to Bitbucket, which could voilate the fair use policy of Bitbucket regarding rate limits. This does not apply to branches and repositories, as these are read-only.
-
For the same reason we simulate the creation of folders by creating a placeholder (
.xillio-api) file in the folder. This file is deleted once another file is created in the same folder. -
Files can be deleted.
-
Files and folders cannot be moved to a different parent.
-
File and folder names cannot contain double quotes (") or slashes (/).
-
When a request for an entity on this connector (a folder or a file) results in a 404, there is no real guarantee that the entity does not exist. The bitbucket API responds with a 500 status on an entity that cannot be found. Therefore we cannot distinguish between a simple file not found or a serious incident with Bitbucket. We do feel that the serious incident is far less likely to happen than that an entity is not found. If it would happen that Bitbucket does have serious problems, there will be other calls that would report the 500 status anyway.
-
The Bitbucket API is rate limited at 30 calls per minute. The connector obeys this limit, however keep in mind that a single endpoint of the Bitbucket connector may result in multiple calls to the Bitbucket API. In case a rate limit is hit, the connector will respond with http status
429 too many requests. -
The Bitbucket API also has hourly and daily rate limits; see https://confluence.atlassian.com/bitbucket/rate-limits-668173227.html for details.
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|
||
|
3.2.3. Mappings
These are the decorators that are set for certain types in Bitbucket.
The connector uses the Repository, Branch, Folder and File types.
The repository and branch types are read-only and cannot be updated.
| Decorator | Used By | Field in Bitbucket | Description |
|---|---|---|---|
|
|
For these types, |
|
|
|||
|
|
|
Other types do not have a creation date. |
|
|
|
The description of a repository when available. |
|
|
Computed from |
The extension of the file, or an empty string if it has none. |
|
|
Computed from |
The sanitized extension of the file. |
|
|
|
The size in bytes of the file. |
|
|
|
The path to the file or folder relative to the branch. For a branch this value is always "/". |
|
|||
|
|||
|
|
Computed from |
The mime type of the requested file, based on the extension. If the extension is unknown this is set to |
|
|
For |
Contains the last modified date of the requested entity, converted to the current time zone. |
|
|
Computed from |
The (full) name of the user that modified this entity, when available. |
|
|
|
The username of the user that modified this entity. |
|
|
Computed from |
The email address of the user that modified this entity, when available. |
|
|
For |
The name of the entity. |
|
|
For |
The name of the file or folder. When a branch contains slashes, the system name shows the slashes replaced with (encoded) spaces. |
|
|
For |
The XDIP of the parent entity. |
|
|
|
Link to the content on the Bitbucket Web UI. |
|
|
|
The version of file - its commit id. |
3.3. Box
Box offers simple, secure file sharing and collaboration from anywhere.
Version(s): we support the latest version of Box.
3.3.1. Configuration
The Box connector uses the OAuth2 web flow for authentication. For more information refer to Get a Box OAuth2 Refresh Token or the Box Documentation.
Create a Box application
This section describes creating a Box application for the Xillio API. This step only has to be done once, even if multiple Box configurations are created.
Before you can start using the Box connector with your application, you will need to setup Box and provide information about your application:
-
Navigate to the developer console.
-
Create a new app.
-
Select the
Custom Appoption. -
Select
Standard OAuth 2.0 (User Authentication)as authentication method. -
Give your app a name and continue by pressing
View Your App. -
Take note of your
Client IDandClient SecretunderConfigurationat the sectionOAuth 2.0 Credentials. -
Set the
Redirect URIunderOAuth 2.0 Redirect URI. Users will be redirected here after authorizing this app. -
Select scopes under
Application Scopes. See Box Application Scopes for more information.
Box Application Scopes
The Box connector requires enabling either of the following scopes in the Box application:
| Scope name | Description |
|---|---|
Read all files and folders stored in Box |
This scope is needed to expose entities' metadata, content and user-defined metadata. |
Read and write all files and folders stored in Box |
This scope is needed to perform write operations such as creating, updating and deleting entities and their content. |
Get a Box OAuth2 Refresh Token
This section describes getting an OAuth2 refresh token to create a Box connector configuration. This step has to be repeated for each Box connector configuration created. Do not share the refreshToken outside of one configuration as Box will invalidate the token.
Authorize the Box Application
Direct the Box user with access to the files and folders that need to be accessed by the Xillio API to the following URL where they will have to enter their Box credentials:
https://account.box.com/api/oauth2/authorize?
response_type=code&
client_id=<your-client-id>& (1)
redirect_uri=<your-redirect-uri> (2)| 1 | Set client_id to the Box client ID from Create a Box application. |
| 2 | Set redirect_uri to the redirect URI specified in Create a Box application. |
After the user authenticates and authorizes the app to access their content, Box will redirect them to the specified redirect URI. The code request parameter contains the authorization code. If the redirect URI points to your own application, handle this request and continue with the following step. Otherwise, copy the authorization code and use it in the following step.
The code is only valid for a short amount of time. Therefore, perform this step and the next request quickly after each other in order to retrieve a refresh token successfully.
Request a Refresh Token
With the authorization code we can now request a Box refresh token:
curl -X POST https://api.box.com/oauth2/token \
-d grant_type=authorization_code \
-d client_id="<your-client-id>" \ (1)
-d client_secret="<your-client-secret>" \ (2)
-d redirect_uri="<your-redirect-uri>" \ (3)
-d code="<your-code>" (4)| 1 | Set client_id to the Box client ID from Create a Box application. |
| 2 | Set client_secret to the Box client secret from Create a Box application. |
| 3 | Set redirect_uri to the redirect URI specified in Create a Box application. |
| 4 | Set code to the authorization code from the previous request. |
Box will return a JSON response with the refresh_token is everything is successful:
{
"access_token": "gc1q8a1pYSxL7VHXsB1CGLOX9E7OjyOq",
"expires_in": 3874,
"restricted_to": [],
"refresh_token": "xi88SOqkEht8lb6fGMvsYJWQne2kUC3gTDeAecQXK6XUkcmxBa1fe1s3zDqWLMyS",
"token_type": "bearer"
}Box can respond with an error if the authorization code is expired:
{
"error": "invalid_grant",
"error_description": "The authorization code has expired"
}Box connector configuration
The Box connector configuration consists of the following values:
| Parameter | Description |
|---|---|
The base URL of the Box API. Default: |
|
The URL of the Box API upload endpoint. Default: |
|
The Box application secret. Required when |
|
The Box application client id. Required when |
|
A Box OAuth2 token. When set, |
|
An OAuth2 refresh token. |
Either token is a required field, or all of refreshToken, clientId and clientSecret are required fields. By only providing a token, you can use a developer token which is valid for 60 minutes, or handle the process of refreshing tokens yourself.
|
{
"configurationType": "Box",
"config" : {
"clientSecret" : "kHsek3Jpji8tgFTcwcnqosfYnxO4unQA",
"clientId" : "m1rvfFhvTCe2a5n7u4eElmOfvvE6WumL",
"refreshToken" : "xi88SOqkEht8lb6fGMvsYJWQne2kUC3gTDeAecQXK6XUkcmxBa1fe1s3zDqWLMyS"
}
}3.3.2. Features and Limitations
Currently, this connector supports operations on files, folders and weblinks. This also includes special files, such as Box Notes.
User-defined Metadata
Box allows you to define your keys in your enterprise metadata templates and custom metadata. These keys do not have to be unique. However, when retrieving the metadata, these identical keys are suffixed with an incremental number.
Furthermore, special characters in keys of enterprise templates will be truncated when retrieving metadata. Any conflict
with another key is then resolved by using an incremental number as a suffix to the key. If the key only contained
special characters, the key will be called field.
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|||
|
3.3.3. Mappings
Entities retrieved through Box can be of kind File, Folder or WebLink. A WebLink is also known as a Bookmark in Box’s UI.
| Decorator | Used By | Field in Box | Description |
|---|---|---|---|
|
|
Whether the entity has children. |
|
|
All entities |
|
The type of the Box entity. |
|
All entities |
The human readable type name. |
|
|
All entities |
|
The date and time the entity was created. This decorator won’t be present if the information is not available. |
|
All entities |
|
The user who created the entity. |
|
All entities |
|
The description of the entity. |
|
|
|
The extension of the file. |
|
|
|
The extension of the file. |
|
|
|
The size of the file in bytes. |
fileSystem.path |
|
|
Computed from the path_collection. |
|
|||
|
|
|
The sha1 hash of the file. |
|
|||
|
|||
|
|
The mime type of the requested file, based on the extension. If the extension is unknown, this is set to |
|
|
All entities |
|
The time the entity was last modified. |
|
All entities |
|
The user who last modified the entity. |
|
All entities |
|
The name of the entity as used in Box. |
|
All entities |
|
The XDIP of the parent entity, as computed using the 'path_collection'. |
|
|
|
The URL of the Bookmark. |
|
|
|
The version number as shown in Box. |
3.4. Contentful
Contentful is content infrastructure. The platform lets you create, manage and distribute content to any platform. Unlike a CMS, Contentful gives you total freedom to create your content model so you can decide which content you want to manage.
With our connector, you can access and translate content stored in Contentful.
3.4.1. Configuration
The most important part of the configuration is the Content management access token. You need to provide this token to allow our connector to navigate and update content created in your apps. This token represents the desired account of your user, and this token will have the same rights as the owner of the account.
There are two types of Content management tokens which you can use:
-
OAuth tokens - they are issued by OAuth applications and represent the user who granted access through this application. These tokens have the same rights as the owner of the account. You can learn more about OAuth applications in Contentful documentation.
-
Personal access tokens - As an alternative to OAuth applications, you can also leverage Personal Access Tokens to use the Content Management API. These tokens are always bound to your individual account, with the same permissions you have on all of your spaces and organizations.
Getting a Content management token
You can create personal access tokens using the Contentful web app. Navigate to the master branch of a space you want to access with the connector. Select Settings/API keys and switch to Content management tokens. Here you can create a token of your choice.
Contentful connector configuration
The Contentful connector configuration consists of the following values:
| Parameter | Description |
|---|---|
The Content management access token. |
|
The ID of the Contentful space you want to access. This value is optional. When not provided the connector will expose all the spaces that the tokens allows accessing. |
|
The environment id of your Contentful Management API. It is necessary to add spaceId if you add environmentId. |
|
Configure the code of the language you consider a source language for the translations. This defines what values the connector exports as content that needs to be translated. |
|
Setting this value to true, the connector will extract only fields of your models that are enabled for translation. Default: |
|
Setting this value to true, the connector will expose linked and referenced items of an Entry as children of the Entry. Setting it to false or leaving it out, there will be no children of Entries. Default: |
{
"configurationType": "Contentful",
"config" : {
"token" : "aHR0cHM6Ly9tZWRpYS5tYWtlYW1lbWUub3JnL2NyZWF0ZWQvZG8teW91LXdhbnQtbmVkZ3Y2LmpwZw==",
"spaceId" : "43bhs4uagphk",
"environmentId" : "master",
"sourceLanguageCode" : "en-US"
}
}3.4.2. Features and Limitations
Connector does not support updating the binary content of the entities as a connector operation. To update the translation of an asset or entry, request creating a new entity. Creating a completely new asset or entry is not possible with the current version of the connector.
Connector does not support entity deletion.
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|||
|
3.4.3. Mappings
These are the decorators that are set for certain kinds of entities in Contentful.
Entities retrieved via Contentful connector can be of kind Space or Environment or ContentModel or Assets or Entry or AssetFile.
| Decorator | Used By | Read-only | Field in Contentful | Description |
|---|---|---|---|---|
|
All entities |
True |
When the entity has children. |
|
|
All entities |
True |
The human-readable name of the content type associated with the requested Contentful entity. |
|
|
All entities |
True |
Computed from |
The name of the content type associated with the requested Contentful entity. |
|
All entities |
True |
|
Date and time when the requested entity was created. |
|
Entries and Assets |
True |
|
|
|
Entries and Assets |
True |
|
|
|
All entities |
True |
|
Last modified date and time of the requested entity. |
|
All entities |
True |
|
The name of the requested entity. |
|
All entities |
False (update this decorator to rename entity or change file’s extension) |
|
The id of the requested entity. |
|
All entities |
True |
The XDIP of the parent entity. |
3.5. Dropbox
Dropbox is a modern workspace designed to reduce busywork—so you can focus on the things that matter.
Version(s): we support the latest version of Dropbox.
3.5.1. Configuration
The configuration for the Dropbox connector consists only of an API token.
| Parameter | Description |
|---|---|
A Dropbox API token. |
To generate a token, visit https://www.dropbox.com/developers/apps and click Create app.
Select the Dropbox API (the Dropbox Business API is not supported by this connector), the type of access, enter a name and click Create app.
You can now get a token by clicking Generate under "Generated access token".
{
"configurationType": "Dropbox",
"config" : {
"token" : "aHR0cHM6Ly9tZWRpYS5tYWtlYW1lbWUub3JnL2NyZWF0ZWQvZG8teW91LXdhbnQtbmVkZ3Y2LmpwZw=="
}
}3.5.2. Named Queries
This connector supports Named Queries.
Due to the underlying Dropbox query API, the expected format for the template field in a named query configuration consists of the serialized version of a JSON structure.
Furthermore, the format of the structure depends on whether searching for file names and content, or metadata properties.
Searching for file names and content
When searching over file names and content, the following format should be used:
{
"path" : "/targetFolder",
"query" : "${q_file_name}",
"mode" : "filename"
}| Field | Description |
|---|---|
|
The root of the search operation, omit, leave empty or null for full repo search |
|
The text to search for in the context given by |
|
The contexts of this search as a comma separated list: |
the filename_and_content mode option is only available to business accounts.
|
The resulting query configuration for the Dropbox query above is therefore:
{
"name" : "myQuery",
"template" : "{\"path\":\"/targetFolder\",\"query\":\"${q_file_name}\",\"mode\":\"filename\"}"
}Searching for metadata properties
When searching over custom metadata properties, the following format should be used:
{
"queries" : [ {
"query" : "${q_property_value}",
"mode" : {
"field_name" : "myProperty",
".tag" : "field_name"
},
"logical_operator" : "or_operator"
} ],
"mode" : "properties",
"template_filter" : "filter_none"
}| Field | Description |
|---|---|
|
List of template ids to restrict the search. |
|
List of matchers for a given property, see next table. |
|
The contexts of this search: the constant |
| Field | Description |
|---|---|
|
Term to search for in the property value. |
|
The logical way this predicate is joined with other condition to determine the match. |
|
Describes the match: currently the |
The resulting query configuration for the metadata properties query above is therefore:
{
"name" : "myQuery",
"template" : "{\"queries\":[{\"query\":\"${q_property_value}\",\"mode\":{\"field_name\":\"myProperty\",\".tag\":\"field_name\"},\"logical_operator\":\"or_operator\"}],\"mode\":\"properties\",\"template_filter\":\"filter_none\"}"
}For an extended explanation of the options and limitations of the Dropbox query (aka "search") API, please consult the official documentation at https://www.dropbox.com/developers/documentation/http/documentation.
3.5.3. Features and Limitations
This connector has the following limitations:
-
The Dropbox Business API is not supported by this connector.
-
The maximum number of file versions that can be returned is 100.
-
Some endpoints, like
/entitieswithmetadatascope, are unavailable when using a Dropbox App with permission/access type "App Folder". Dropbox unfortunately does not give access to the necessary endpoints for these kind of apps. -
Querying for
"(double quotes) never yields results. -
Querying for metadata properties only returns files which are not deleted.
-
Full text search on the
/searchendpoint is only supported for Dropbox Business accounts. For other accounts it will only search the file names.
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|
||
|
3.5.4. Mappings
These are the decorators set for certain types in Dropbox.
Like on a regular filesystem, an entity can be of kind File or Folder.
| Decorator | Used By | Field in Dropbox | Description |
|---|---|---|---|
|
|
This decorator is only set for folders, and |
|
|
|
This value is set to |
|
|
|
This value is set to |
|
|
|||
|
|||
|
|
|
The extension of the file, or an empty string if it has none. Computed from the file name. |
|
|
|
The sanitized extension of the file. Computed from the file name. |
|
|
|
The size in bytes of the file. |
|
|
|
The path to the file or folder relative to the Dropbox root. |
|
|||
|
|||
|
|
|
The |
|
|||
|
|
The mime type of the requested file, based on the extension. If the extension is unknown this is set to |
|
|
|
|
Contains the last modified date of the requested file, converted to the current time zone. |
|
|||
|
|
|
The name of the file or folder. |
|
|
|
The name of the file or folder. |
|
|
|
The XDIP of the parent entity. Computed from the display path of the entity. |
|
|||
|
|
|
The revision number of the file. |
3.6. Drupal
Drupal is an open source platform for building amazing digital experiences. It’s made by a dedicated community. Anyone can use it, and it will always be free.
Version(s): we support version 9 of Drupal.
3.6.1. Preqrequisites in Drupal system configuration
In order to enable translation support for Drupal, the next steps have to be followed:
To connect to Drupal, we need to have the following modules installed.
You can install these under Manage → Extend.
-
Http Basic Authentication Module
-
JSON:API Module
-
Serialization Module
In addition, permissions for users will have to be modified.
You can find the user permissions under Manage → People → Permissions.
-
To use the connector, your user must have the
View published contentpermission. To also see unpublished content authored by your own user, you also need theView own unpublished contentpermission. To see any unpublished content by any user, you need either theAdministratorrole or theBypass content access controlpermission. -
If the user does not have the correct permission to retrieve the information of a
Node, it could be that no data is returned with anHTTP OK 200response.
Furthermore, to support write-operation, you need to configure the JSON API to allow such operations.
You can configure this at Manage → Configuration → Web Services → JSON:API and then check Accept all JSON:API create,
read, update, and delete operations.
Translation prerequisites
In order to enable the translation support with drupal the next steps have to be followed.
-
Install
JSON:API Translationmodule underManage → Extend → Core(Experimental). -
To support the
translationrelation type, you need to have set up Drupal for translation management as well. This requires thecontent translationandlanguagemodules. Furthermore, the supported languages in Drupal needs to be configured atconfiguration → languages. -
The types of content supporting translation need to be configured as well at
configuration → content language and translation. In order to translate articles and web-pages, the boxcontentneeds to be ticked in this window.
Making use of the translation features when the JSON:API Translation module has not been successfully
installed can result in undesired effects. This module allows recognizing the translations of a node, without it, any
modifications might be applied to the default node as an undesired result. That is why it is advised thoroughly to
follow all the steps described above.
|
3.6.2. Configuration
The Drupal connector uses basic authentication as supported by Drupal’s 'HTTP Basic Authentication module'. If you would rather configure this connector to use JWT tokens issues by your JWT module, please contact us to provide support for this in the connector.
The Drupal connector configuration consists of the following values:
| Parameter | Description |
|---|---|
The username of an account on Drupal. |
|
The password of the account. |
|
The URL to the JSON:API module of Drupal. |
An example configuration for the Drupal connector would be:
{
"configurationType": "Drupal",
"config" : {
"username" : "username",
"password" : "password",
"baseUrl" : "https://my-drupal-website:8084/jsonapi"
}
}3.6.3. Features and Limitations
-
On the
contentsendpoint, we expose a JSON structure of thebodyfield and fields starting with the system namefield_. A custom field might contain only system information, such as for a custom field of typecomment. See at the bottom of this section an example of these contents. The same JSON structure can be used to update content. If a value of a field in this JSON structure is set tonull, it will be ignored by Drupal. -
Currently, the connector does not expose attachments nor images yet.
-
The maximum limit used in pagination is 50.
-
The
workflow.status.normalizeddecorator field will exposePUBLISHEDif there is at least one revision of the node that is published, even when there is a newerDRAFTrevision. This is a limitation of the Drupal API.
Translation support for this connector is limited due to a number of bugs in Drupal. The following limitations have been recorded:
-
Currently, it is only possible to create translations on published nodes. Creating translations of a draft node is not supported by Drupal at this moment.
-
Currently, it is only possible to update translation nodes when they and their original node are published.
-
Currently, only the title, status and contents of translation nodes can be updated. For original nodes, the title, status, language and contents can be updated. Changing the language of an original node will result in not being able to alter it again as the node can not be reached anymore due to a bug in the Drupal core API.
-
Currently, you can not yet delete an existing translation due to a bug in Drupal translation API.
-
For original languages, the API currently only exposes the latest published version of that node. If there is no latest published version, it will show the latest draft version instead. For non-original translations of a node, the API will also only expose the latest published version of that translation. If there is no latest published version of a translation, it will not expose the translation at all using the
translation_all_*on the original node. Furthermore, direct retrieval of the translation using thelanguagequery parameter will result in the original language node being returned. Therefore it might seem that your entity is already published, but a previous version or other translation of that entity is shown instead. Be extra careful by looking at which language and what status of the entity is returned.
{
"body": {
"value": "<p>Pita bread with shawarma and optional ingredients.</p>\r\n",
"format": "basic_html",
"processed": "<p>Pita bread with shawarma and optional ingredients.</p>",
"summary": ""
},
"field_subtitle": "Middle-eastern meat dish",
"field_duration": 15,
"field_instructions": {
"value": "<ul>\r\n\t<li>Cook shawarma</li>\r\n\t<li>Heat pita bread</li>\r\n\t<li>Put cooked shawarma in pita bread with optional ingredients (lettuce, garlic sauce, cheese)</li>\r\n</ul>\r\n",
"format": "basic_html",
"processed": "<ul><li>Cook shawarma</li>\n\t<li>Heat pita bread</li>\n\t<li>Put cooked shawarma in pita bread with optional ingredients (lettuce, garlic sauce, cheese)</li>\n</ul>"
},
"field_recipe_comments": {
"status": 2,
"cid": 4,
"last_comment_timestamp": 1601458996,
"last_comment_name": "",
"last_comment_uid": 1,
"comment_count": 1
}
}Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|||
|
|
3.6.4. Mappings
| Decorator | Used By | Field in Drupal | Description |
|---|---|---|---|
|
|
Whether the entity can have |
|
|
|
|
The type of the node. |
|
|
|
The internal name for the node type. |
|
|
|
Contains the creation date of the requested node. |
|
|
|
The ID of the user that created this node. |
|
|
|
The description of the node type. |
|
|
|
Contains the amount of bytes that would be returned in the contents call. |
|
|
|
The language of the node (type). |
|
|
|
The title of the node. |
|
|
|
The name of the node type. |
|
|
|
The ID of the node. |
|
|
|
The internal name of the node type. |
|
|
Present when the node contains content (a |
|
|
|
|
Contains the last modified date of the requested node. |
|
|
|
The ID of the user that last modified this node. |
|
|
The parent XDIP. In the case of a |
|
|
|
|
Whether the node (type) is published/visible. |
3.7. Egnyte
Go beyond secure file sharing with a solution that helps businesses work better and safer on any device, from anywhere, and with any app they choose.
Version(s): we support the latest online version of Egnyte.
3.7.1. Configuration
Before you can start using the Egnyte connector, you will need to setup an Egnyte domain and request an API token for that domain:
-
Register an Egnyte account if you don’t have one yet.
-
Register an Egnyte developer account here if you don’t have one yet (use the domain from the step 1 and set your application as "Internal").
-
Once the API key has been approved by Egnyte, authenticate it with the domain from step 1. The approval may take some time as they approve the API keys manually.
The configuration consists of both an Egnyte access token and the URL of your domain.
| Parameter | Description |
|---|---|
The base URL of the Egnyte instance. |
|
An Egnyte OAuth2 token. |
{
"configurationType": "Egnyte",
"config" : {
"address" : "https://example.egnyte.com",
"token" : "aHR0cHM6Ly9tZWRpYS5tYWtlYW1lbWUub3JnL2NyZWF0ZWQvZG8teW91LXdhbnQtbmVkZ3Y2LmpwZw=="
}
}Getting your token
To get your access token you make a curl request like this:
curl -X POST \
-d grant_type=password \
-d username="<your-egnyte-username>" \ (1)
-d password="<your-egnyte-password>" \ (2)
-d client_id="<your-client-id>" \ (3)
https://<your-domain>.egnyte.com/puboauth/token (4)| 1 | Set username of an administrator account of your Egnyte domain |
| 2 | Set password of the administrator account that you use |
| 3 | Set client_id to the API key that was approved by Egnyte |
| 4 | Set domain to the domain name that you use for your Egnyte service |
On success, this returns:
{
"access_token": "68zc95e3xv954u6k3hbnma3q",
"token_type": "bearer",
"expires_in": -1
}The access_token can now be used in the connector configuration.
For more information and possible errors see Egnyte’s manual.
3.7.2. Features and Limitations
-
Note that by default all API keys are set to 2 queries per second and a 1000 call daily limit. This is a per user per domain limit that Egnyte imposes.
-
A
403 - FORBIDDENHTTP response code can be caused by either a wrong access token or a wrong domain name that does exist. -
When deleting a file or folder it will be moved to the "Trash" from where it will be permanently deleted after one month.
Rate Limiting
Egnyte has an aggressive rate limit where you can only do two requests per token per second. Xillio API retries the request after one second when encountering rate limit errors for a maximum of five times. We do this for all operations except for operations containing binary data (Create a New Entity With Contents and Update an Entity's Contents).
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|
|
|
|
3.7.3. Mappings
| Decorator | Used By | Field in Egnyte | Description |
|---|---|---|---|
|
|
Whether the entity has children. |
|
|
|||
|
|||
|
|||
|
|||
|
|
Computed from |
|
|
|
Computed from |
|
|
|
|
The size of the file in bytes. |
fileSystem.path |
All entities |
|
The path in the Egnyte domain that the entity can be found at. |
|
|||
|
|||
|
|||
|
|||
|
|
The mime type of the requested file, based on the extension. If the extension is unknown, this is set to |
|
|
All entities |
|
The date and time the file or folder was last modified. |
|
All entities |
|
The user who last modified the entity. |
|
All entities |
|
The name of the entity as used in Egnyte. |
|
All entities |
Computed from |
|
|
|||
|
|
|
The version id of the file. |
3.8. Episerver10
Episerver is a solution that enables you to manage content and campaigns in one screen.
Version(s): we support version 10 of Episerver.
3.8.1. Configuration
To configure Episerver you need the following:
| Parameter | Description |
|---|---|
The URL of the Episerver instance. |
|
The username of an account on Episerver. |
|
The password of the account. |
|
An Episerver OAuth2 token. A token lasts 5 minutes after which a new one will be requested. Optional if supplying a |
The baseUrl value needs to end with /episerverapi.
|
{
"configurationType": "Episerver10",
"config" : {
"baseUrl" : "http://my-domain.com:49700/episerverapi",
"username" : "username",
"password" : "password"
}
}Episerver Service Extension
To allow communication with your Episerver instance, a Xillio API service extension is required. In the next section you are guided through the installation of that extension.
Setup
In order for the Xillio Episerver extension to work some conditions need to be met:
-
A working Episerver instance must be available.
-
The
EPiServer.ServiceApiNuGet package should be installed from the Episerver NuGet feed. For more infomation visit: Adding the Episerver NuGet feed. -
The command
update-epidatabaseshould be ran in the Package Manager console.
The extension can be added to the Episerver by creating a new reference to the extension source code. By completing the following steps you can add this reference.
-
Clone/Download the extension source code, which can be found at https://github.com/xillio/ServiceAPIExtensions, to your system.
-
Open the solution for your Episerver site in Visual Studio.
-
Right-click the Episerver site and select 'Add > Existing Item…'.
-
In the file browser dialog, search for the source code. Add the
ContentApiController.csfile. -
Add
app.UseServiceApiIdentityTokenAuthorization<ApplicationUserManager<ApplicationUser>, ApplicationUser>();to the Startup.cs. -
Build the solution ([Ctrl+Shift+B]). Once the build succeeds the Episerver can be started. Go to
{episerver-address}/episerverto verify that it is running. -
Once logged in with your admin credentials you can go to
CMS > Admin > Config > Permissions for functions. In here you have to allow users to use theEpiserverServiceApiand all of its functions. (Not permitting a user means that some functionality can’t be accessed). -
Now the extension is ready to be used with the Xillio API.
3.8.2. Features and Limitations
Data Hierarchy
The data hierarchy of the Episerver CMS is as follows:
-
Pages have pages as parent.
-
Files have folders or pages as parents.
-
Folders have other folders or pages as parent.
-
Blocks have folders as parents.
-
The children of a page contain child pages, referenced blocks and content.
-
The children of a folder contain the folders, files and blocks that are inside the folder.
-
Blocks and files have no children.
-
Pages and Blocks can exist in multiple languages.
| Content Type | Children | Parent | Translations |
|---|---|---|---|
Block |
Folder |
||
File |
Folder, Page |
||
Folder |
Block, File, Folder |
Folder, Page |
|
Page |
Block, File, Folder, Page |
Page |
Supported Content Types
The only types that are supported are types that fall into the following categories.
Pages
All kinds of page types. For more info on pages visit Episerver documentation.
When a request is made for the content of a page. The response will return all fields of the page as a JSON.
{
"Name": "Whitepaper",
"ParentLink": "9",
"ContentGuid": "ee643f9d-a5c4-4013-a76f-dbfd73190121",
"ContentLink": "12",
"ContentTypeID": 23,
"__EpiserverContentType": "StandardPage",
"__EpiserverBaseContentType": "Page",
"__EpiserverAvailableLanguages": [
"en",
"nl-NL"
],
"__EpiserverDefaultLanguage": "en",
"__EpiserverCurrentLanguage": "nl-NL",
"PageLink": "12",
"PageTypeID": 23,
"PageParentLink": "9",
"PagePendingPublish": false,
"PageWorkStatus": 4,
"PageDeleted": false,
"PageSaved": "2017-08-25T16:38:12+02:00",
"PageTypeName": "StandardPage",
"PageChanged": "2017-08-25T16:38:12+02:00",
"PageCreatedBy": "",
"PageChangedBy": "",
"PageMasterLanguageBranch": "en",
"PageLanguageBranch": "en",
"PageGUID": "ee643f9d-a5c4-4013-a76f-dbfd73190121",
"PageContentAssetsID": "2d1dca96-2f80-4576-82f1-fe403379f654",
"PageName": "Whitepaper",
"PageVisibleInMenu": true,
"PageURLSegment": "download-whitepaper-alloy-track",
"PageChildOrderRule": 1,
"PagePeerOrder": 4,
"PageChangedOnPublish": false,
"PageCategory": "Track",
"PageStartPublish": "2012-09-13T16:04:17+02:00",
"PageCreated": "2012-09-13T16:04:17+02:00",
"PageShortcutType": 0,
"PageLinkURL": "/link/ee643f9da5c44013a76fdbfd73190121.aspx",
"MetaTitle": "Alloy Track Whitepaper",
"PageImage": "83",
"MetaKeywords": [
"Alloy Track Whitepaper",
"Online project tracking"
],
"TeaserText": "Explore the opportunities that exist for keeping your projects on track.",
"MetaDescription": "Making sure that your project is on-track.",
"MainBody": "<p><img style=\"float: left;\" src=\"/link/3864e90c32b642f6bd523992a49c9f30.png\" alt=\"Download Whitepaper Alloy Track\" width=\"300\" height=\"205\" />Learn from the experiences of our many customers who have contributed to this whitepaper.</p>\n<p>Projects have a natural lifecycle with well-defined stages. Progress monitoring is a critical part of making sure that your project is on-track and capable of delivering in the end.</p>\n<p>From start-up meetings to final sign-off, we have the solutions for today's market-driven needs. Leverage your assets to the fullest through the combination of Alloy Plan, Alloy Meet and Alloy Track.</p>",
"MainContentArea": [
85
]
}The same applies for creating and updating content on a page.
Blocks
All kinds of block types. For more info on blocks visit Episerver documentation.
When a request is made for the content of a block. The response will return all fields in the block as a JSON object.
{
"Name": "Alloy Meet jumbotron",
"ParentLink": "50",
"ContentGuid": "18d75471-54fc-462f-9114-e745a8ea6127",
"ContentLink": "51",
"ContentTypeID": 12,
"__EpiserverContentType": "JumbotronBlock",
"__EpiserverBaseContentType": "Block",
"__EpiserverAvailableLanguages": [
"en"
],
"__EpiserverDefaultLanguage": "en",
"__EpiserverCurrentLanguage": "en",
"Image": "150",
"ImageDescription": "Some happy people cheering",
"Heading": "Wherever you meet!",
"SubHeading": "Alloy solves the two most pressing problems in long distance collaboration – better communication and better project management ",
"ButtonText": "Read more",
"ButtonLink": "/link/33b0aa1ca429426c8d05d97d6cbd7f7a.aspx"
}The same applies for creating and updating content in a block.
Folders
Only the basic CMS folder is supported.
Files
All file and media types are supported.
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|||
|
|
3.8.3. Mappings
These are the decorators that are set for Episerver.
| Decorator | Used By | Episerver property | Description |
|---|---|---|---|
|
All entities |
|
Whether the entity has children or not. |
|
All entities |
|
The content type returned by Episerver. |
|
All entities |
|
The content type returned by Episerver. |
|
|
|
The time the page was created in ISO UTC format. |
|
|
|
The user that created the page. |
|
|
|
The description of a page. |
|
|
Computed from the name of the file. |
The extension of the file. |
|
|
Computed from the rawExtension. |
The sanitized extension of the file. |
|
|
|
The size of the file in bytes. |
|
|||
|
|||
|
|||
|
|
|
The |
|
|
The language tag of the requested page or block. |
|
|
|
The master language of the page or block. |
|
|
|
|
The mime type of the requested file, based on the extension. If the extension is unknown this is set to |
|
|
|
The time the page was last modified in ISO UTC format. |
|
|
|
The user that last modified the page. |
|
All entities |
Page: The "MetaTitle" of the page. Folder, Block and File: The "Name" of the object. |
The human readable name of the entity. |
|
All entities |
|
The name of the object as used in the Episerver backend. |
|
All entities |
Computed using |
The XDIP of the parent entity. |
|
|||
|
3.9. IBM FileNet
IBM FileNet Content Manager is a document management engine for enterprise content, security and storage features plus process management capabilities.
The FileNet connector allows connecting to an object store of the FileNet Content Engine and manipulate its folders and documents.
Version(s): we support version 5.2.X of FileNet.
3.9.1. Configuration
The FileNet connector configuration consists of the following values:
| Parameter | Description |
|---|---|
The URL of the FileNet server API extension. |
|
The username of an account on Filenet. |
|
The password of the account. |
|
The name of the object store to which to connect. |
|
The communication protocol to use. If not sure about what value to use for stanza, leave empty, the Web Service Interface will be used by default. Default: |
A configuration allows access to a single object store only.
{
"configurationType": "Filenet",
"config" : {
"baseUrl" : "http://filenet.xillio.com:9080/wsi/FNCEWS40MTOM",
"username" : "username",
"password" : "password",
"objectstore" : "objectstore"
}
}3.9.2. Features and Limitations
The FileNet connector supports two types of content: documents and folders.
Multiple parents of a document
FileNet supports documents (not folders) to have multiple parents at the same time.
The Xillio API entity endpoint is not capable of this at the moment and our FileNet connector will always return only one parent of the document. This will be always the parent with lowest FileNet
Although the FileNet connector cannot deliver multiple parents of a document, it allows to add or remove additional parents. The following table shows how to add, remove or update parent reference of the document with FileNet connector.
The complete document parent list can be accessed using the metadata scope.
| Action | Parent in "original" section | Parent in "modified" section |
|---|---|---|
Move document |
||
Add new parent link |
||
Remove parent link |
You can remove all the parent links of a document in this way.
There is no support for multiple parents for folders in FileNet. So in case of a folder the parent in the "original" section of the update entity request is ignored and the folder can only be moved to the new folder defined by the parent.id in the "modified" section of the update entity request.
ID-based identification of the entities
Our FileNet connector is using FileNet internal IDs as a part of the entity’s XDIP. This allows multiple documents in the same folder to have the same name just like in FileNet itself. Similarly the names of subfolders of a certain folder need to be unique as this is a limitation of FileNet.
Be aware that Filenet assigns different IDs to different versions of a document and that uploading new content for a document with the Xillio API creates a new version of that document. Therefore we recommend that you get the ID of the latest version of a document after uploading new content before you continue working with it. To get the ID of the latest version you might request the versions or list of versions of that entity and get the latest version from there including its ID.
Keep in mind that deleting a specific version of an entity will use the ID in the xdip to remove it.
You can still use the parameter in an XDIP to reference other versions of the document. Assume for example that AAA is the ID of version 1.0 of a document and BBB is the ID of version 2.0 of that document. You can request an entity xdip://{configuration ID}/AAA?version=2.0 and you will get the metadata of version 2.0 as if you would request xdip://{configuration ID}/BBB. Also requesting xdip://{configuration ID}/AAA?scope=versions returns the same result as a request for xdip://{configuration ID}/BBB?scope=versions.
Documents with no parent folder
FileNet allows documents to have no parent folder. Such a document is not shown using IBM Filenet Navigator UI, but it can still be found through the "Search" function. Similarly, with our connector if you know the ID of the document you can do all the common operations on the document using its ID, but you will never get this document iterating over the files and folders in the object store.
Metadata of such a document won’t contain the parent decorator to indicate that there is no parent folder assigned to this document in FileNet.
Documents in the root of the object store
Though the IBM Filenet Navigator UI is not showing any documents in the root of the object store it is possible to create, update and delete such documents and our FileNet connector allows these operations.
Querying documents and folders
This connector supports Named Queries.
The Content Engine supports an SQL-92-like query language. Check IBM Filenet Documentation
For example, the following query will return documents added in the last three days:
{
"name" : "created_in_3_days",
"template" : "SELECT * FROM Document WHERE DateCreated > Now() - TimeSpan(3, 'Days')"
}
It is possible to query for documents by the values of their properties, as defined in the templates assigned to them.
Use the Symbolic name of the property in query predicates.
Let’s assume TestNumber is the Symbolic name of a property inherited by your documents, then the following query will find documents with a specific value for it:
{
"name" : "test_number",
"template" : "SELECT * FROM Document WHERE TestNumber = ${q_myvariable}"
}
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|
||
|
3.9.3. Mappings
The FileNet connector supports two types of entities: documents and folders. This connector does not specify which fields from FileNet are mapped to the decorators since the FileNet API extension defines these fields itself.
| Decorator | Used By | Description |
|---|---|---|
|
|
This decorator is only set for folders and |
|
|
This value is set to |
|
|
This value is set to |
|
|
Date and time when the requested entity was created. |
|
|
Name of the user that created the requested entity. |
|
|
The extension of the document or an empty string if it has none. |
|
|
The sanitized extension of the document. |
|
|
The size in bytes of the document. |
|
|
The path through the entity’s parent to this resource. |
|
|
The mime type as supplied by FileNet. |
|
|
Last modified date and time of the requested entity. |
|
|
Name of the user that modified the requested entity last. |
|
|
The name of the requested entity. Always the same as name.systemName. |
|
|
The name of the requested entity. |
|
|
The XDIP of the parent entity. See the Multiple parents of a document section for more details. |
|
|
The version number of the document. |
3.10. GitLab
GitLab provides a Git-like experience while providing CI and many more perks to developer teams.
Version(s): we support version 4 of the GitLab API on GitLab 11.1.0 and newer.
3.10.1. Configuration
The GitLab connector gives access to a single GitLab git repository per configuration. A repository is identified by its GitLab project ID. The GitLab connector uses Personal Access Tokens or the OAuth2 web flow for authentication. For more information refer to Get a GitLab OAuth2 Refresh Token or the GitLab Documentation.
Using a Personal Access Token
-
Navigate to the GitLab user settings
-
Click Access Tokens
-
Enter a name for your token
-
Select the
apiscope -
Click Create personal access token
-
Copy the personal access token to your Xillio API configuration’s
tokenfield
Using OAuth
Create a GitLab application
This section describes creating a GitLab application for the Xillio API. This step only has to be done once, even if multiple GitLab configurations are created.
-
Navigate to the GitLab user settings
-
Open the Applications tab
-
Add a new application with a redirect URI that can handle OAuth code callbacks (this could be your own web application or
https://localhostfor testing purposes) and theapiscope only
When requesting an OAuth2 authorization code, GitLab will return a redirect to the redirect URI with the code request parameter containing the authorization code. This should normally be handled by your own web application. However, using https://localhost as a redirect URI can be helpful for testing since the authorization code can simply be copied from the browser manually and used to request a refresh token.
|
Get a GitLab OAuth2 Refresh Token
This section describes getting an OAuth2 refresh token to create a GitLab connector configuration. This step has to be repeated for each GitLab connector configuration created.
Direct the GitLab user with access to the GitLab projects that need to be exposed by the Xillio API to the following URL where they will have to enter their GitLab credentials:
https://gitlab.com/oauth/authorize? (1)
response_type=code
client_id=<your-application-id>& (2)
redirect_uri=<your-redirect-uri> (3)| 1 | This endpoint handles authorization code requests. Replace gitlab.com with the hostname of your GitLab instance, if not using the GitLab cloud solution. |
| 2 | Set client_id to the GitLab application ID from Create a GitLab application. |
| 3 | Set redirect_uri to the redirect URI specified in Create a GitLab application. |
GitLab will respond with a redirect to the specified redirect URI. The code request parameter contains the authorization code. If the redirect URI points to your own application, handle this request and continue with the following step. Otherwise, copy the authorization code and use it in the following step.
Request a refresh token:
curl -X POST https://gitlab.com/oauth/token \ (1)
-d grant_type=authorization_code \
-d client_id="<your-application-id>" \ (2)
-d client_secret="<your-application-secret>" \ (3)
-d redirect_uri="<your-redirect-uri>" \ (4)
-d code="<your-code>" (5)| 1 | This endpoint handles OAuth2 token requests. Replace gitlab.com with the hostname of your GitLab instance, if not using the GitLab cloud solution. |
| 2 | Set client_id to the GitLab application ID from Create a GitLab application. |
| 3 | Set client_secret to the GitLab application secret from Create a GitLab application. |
| 4 | Set redirect_uri to the redirect URI specified in Create a GitLab application. |
| 5 | Set code to the authorization code from the previous request. |
Connector Configuration
The GitLab connector configuration consists of the following values:
| Parameter | Description |
|---|---|
The base URL to the GitLab instance. Default: |
|
The GitLab application client id. Required when |
|
The GitLab application secret. Required when |
|
A GitLab personal access token, or a GitLab OAuth2 token. When set, |
|
An OAuth2 refresh token. See Get a GitLab OAuth2 Refresh Token for information on acquiring a refresh token. |
|
The id of the GitLab project. It can be specified either by name (e.g. |
{
"configurationType": "GitLab",
"config" : {
"clientId" : "client-id",
"clientSecret" : "client-secret",
"refreshToken" : "fdb8fdbecf1d03ce5e6125c067733c0d51de209c",
"projectId" : "MyGroup/MyProject"
}
}3.10.2. Features and Limitations
-
This connector supports read and write operations on folders and files.
-
This connector supports only read operations on branches.
-
The
pathrelation of this connector returns different kinds of entities depending on the level ofchildren:-
branches for the children of the root,
-
files and folders on subsequent levels.
-
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|||
|
3.10.3. Mappings
| Decorator | Used By | Field in GitLab | Description |
|---|---|---|---|
|
|
Whether the entity can have |
|
|
|
Computed from |
The extension of the file. |
|
|
Computed from |
The extension of the file. |
|
|
|
The size of the file in bytes. |
|
|
|
The absolute path from the root of the repository to the entity. |
|
|
|
The sha256 hash of the file. |
|
|
The mime type of the requested file, based on the extension. If the extension is unknown, this is set to |
|
|
|
|
The date of the last modifying commit for files. The date of the last commit for branches. |
|
|
|
The name and e-mail of the author. Git also has a concept of committer, which is not represented by the GitLab connector. |
|
|
|
The file name, including extension. |
|
|
|
The file name, including extension. |
|
|
The ID of the connector configuration for branches, the ID of the branch for root level files and folders, the ID of the parent folder otherwise. |
|
|
|
|
The |
3.11. Google Drive
Google Drive provides cloud storage and file backup.
Version(s): we support the latest version of Google Drive.
3.11.1. Configuration
Google Drive uses OAuth2 to secure the web api. This means you will need an app which you can use to generate access tokens.
Create an API app
To set up the Google Drive connector you need a Google API app.
-
If you don’t have a google developer project, create one.
-
Search for 'Google Drive API' in the API-Library.
-
Enable 'Google Drive API'.
-
Open the OAuth Consent screen.
-
Set a 'Product name'. This is the name that shows up when you try to authenticate a user.
-
Open the Credentials overview.
-
Create a new 'OAuth Client ID' and select 'Other client'.
Get a Refresh Token
The refresh token allows Xillio API to receive a new access token automatically after the current one has expired. To get your initial refresh token, you have to go through the OAuth code flow of Google. You will need the details of the API app you created in the previous step.
Enter the following URL in your browser:
https://accounts.google.com/o/oauth2/v2/auth (1)
?response_type=code (2)
&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob (3)
&client_id=<your-client-id> (4)
&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive (5)
&access_type=offline (6)
If you decide to use any outer redirect_uri, you should add it to your application first. Otherwise, an attempt of receiving a refresh token will fail. To add your custom redirect_uri, go to Credentials screen, select your application and add your uri to the Authorized redirect URIs
|
| 1 | https://accounts.google.com/o/oauth2/v2/auth is the main authentication endpoint |
| 2 | The response_type can be set to either code, which provides a code that can be used to get a new token, or token, which will return a short-lived token. As you need a refresh token, use the value code. |
| 3 | Set the redirect_uri to the uri to which the user should return after authorization. If you don’t have a redirect uri you can use, use urn:ietf:wg:oauth:2.0:oob to prompt the user to manually copy the code. |
| 4 | Enter here the client ID of your registered app. You can find your client_id in Credentials overview. |
| 5 | The https://www.googleapis.com/auth/drive scope is required to manipulate and inspect files in the user’s drive. |
| 6 | The access_type value offline is required to make Google API return you a refresh token. With refresh token Xillio API can later renew access tokens automatically for you. If you omit this parameter, you will receive only access token. Access token is typically only for 1 hour and you will have to renew it later manually. |
The browser will ask you to select a Google account that you want to connect to and to authorize the access to your data. After approving the access you will be redirected to redirect_uri you have specified and the URL. It doesn’t matter if there is no content on that URL. You only need to check the URL you were redirected to. It will contain a query parameter code. You need to get that code. You will exchange it for token during the next step.
Make a Google OAuth endpoint POST request like this one
curl -X POST https://www.googleapis.com/oauth2/v4/token \
-d grant_type=authorization_code \
-d redirect_uri="urn:ietf:wg:oauth:2.0:oob" \ (1)
-d client_id="<your-client-id>" \ (2)
-d client_secret="<your-client-secret>" \ (3)
-d code="<your-code>" (4)| 1 | The redirect_uri must be set to the same URI as you used earlier to request the code. |
| 2 | You can find your client_id in your Credentials overview. |
| 3 | You can find your client_secret in your Credentials overview. |
| 4 | Insert the code you got from the URL at the end of the previous step. |
You should get a response like this:
{
"access_token": "<< ACCESS_TOKEN >>",
"expires_in": 3599,
"refresh_token": "<< REFRESH_TOKEN >>",
"scope": "https://www.googleapis.com/auth/drive",
"token_type": "Bearer"
}The value refresh_token is what you will need later when setting up a configuration to access the Google Drive you have selected during this flow.
Connector Configuration
The connector configuration consists of the following values:
| Parameter | Description |
|---|---|
The base URL of the Google Drive API. Default: |
|
The token URL of the Google authorization server. |
|
The Google Drive application client id. Required when |
|
The Google Drive application secret. Required when |
|
A Google Drive OAuth2 token. When set, |
|
An OAuth2 refresh token. See Get a Refresh Token for information on acquiring a refresh token. |
|
It is not possible to download the Google Docs format via Xillio API directly. The The The key must be a If the what means you are trying to export a document format as a Please refer to the official Google documentation to find everything out about different mimeTypes and their compatibility. Each Google doc format can be exported only into one format in each distinct mimeTypeMapping. If you enter several export formats for the same Google Docs format e.g. only the last one will be used. As were said, the If you don’t set up the |
By providing a refresh token, client id and client secret, the Xillio API will refresh the access token when it expires. In that case, and if the connector operation does not concern binary data, the Xillio API will then retry the request with the new access token.
{
"id": "googledrive",
"name": "googledrive",
"configurationType": "GoogleDrive",
"passthroughAuthorization": false,
"config": {
"clientId": "826514876365-m4hltubt3d3tvu7iu2875m5pvum0fm8l.apps.googleusercontent.com",
"clientSecret": "BAHEfQjVAN-GVZ9IV9EPbPg_",
"refreshToken": "4/0AX4XfWgJF1PCbNZmeNwzdJJZi0YEGlRMFGgeiqglu5H2mkt0hJe6b-Tb59YsWx6jiPrflg",
"mimeTypeMapping": {
"application/vnd.google-apps.document": "text/plain",
"application/vnd.google-apps.spreadsheet": "text/csv"
}
}
}If you plan to use only access token (you need one time access, or you plan refreshing the token yourself), you should create a configuration like this one
{
"id": "googledrive",
"name": "googledrive",
"configurationType": "GoogleDrive",
"passthroughAuthorization": false,
"config": {
"token": "ya29.a0ARrdaM_HeAbvtvsIOK2m12dbiZcyCpHnSUFv2NXVDSpdUXCUt8mPo0T5G76_qPtFZtBi38AZrISAm1VtZIIpuIADUoxBvRWDd14vGqHvpaFR7sesocJbCRVMRyEZ6zZYFcTL2GfXuyXRB4xlE1vCgiAk221O",
"mimeTypeMapping": {
"application/vnd.google-apps.document": "text/plain",
"application/vnd.google-apps.spreadsheet": "text/csv"
}
}
}3.11.2. Features and Limitations
Named Queries
This connector supports Named Queries. An example query configuration would be:
{
"name": "fileExcludingTerm",
"template": "name = '${q_name}' and not fullText contains '${q_exclude_term}'"
}Please consult the Google Drive API documentation for the full query syntax.
Including Google Drive special characters like ' or " in a search clause without any other characters will not yield any results.
|
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|
||
|
3.11.3. Mappings
These are the decorators that are set for certain types in Google Drive.
A file is considered to have 'binary contents' when it is a file (not a folder) and it is not a Google Docs document from an application such as Google Sheets, Google Slides or Google Docs.
| Decorator | Used By | Field in Google Drive | Description |
|---|---|---|---|
|
|
This decorator is only set for folders, and |
|
|
|
|
Is set to |
|
|
|
Is set to |
|
|
|
The created decorator is always set but only contains the |
|
|
|
The |
|
|
|
The extension of the file, or an empty string if it has none. |
|
|
The sanitized extension of the file. |
|
|
|
|
The size in bytes of the file. |
|
|
|
The md5 hash is set if the file contains contents (i.e. is not a Google Docs document). |
|
|
|
The mime type as evaluated by Google Drive. If the mime type is unknown by Google Drive it is based on the extension.
If there is no extension the mime type is |
|
|
|
Contains the last modified date of the requested file, converted to the current time zone. |
|
|
|
Contains information about the user who last modified this file or folder. |
|
|
|
The human readable (or chosen) name of the file or folder. |
|
|
|
The human readable (or chosen) name of the file or folder. |
|
|
|
The XDIP of the parent entity. |
|
|
|
The link to the file in google drive. |
|
|
|
The version number of the file or folder. |
3.12. JSON RPC
This Connector allows to use third-party connector implementations running as HTTP(S) services independent of the Engine.
Along with enabling anyone to write his own connector, this architecture allows a quicker release for experimental connectors outside of the stringent quality bounds of the Engine.
For every request to the JSON RPC connector the configuration is sent to the external connector along with the request parameters and body.
As a consequence the external connector can be fully stateless.
3.12.1. Configuration
The configuration of a JSON RPC connector includes just the URL of the external connector and the configuration for it.
A switch is provided to allow non secure HTTPS connections for development.
| Parameter | Description | ||||
|---|---|---|---|---|---|
The URL of the remote JSON RPC connector endpoint that is going to execute the requests for this configuration. |
|||||
When set to
Default: |
|||||
The external JSON RPC connector configuration fields in the form a JSON object with field names as keys and field values as values.
For example, if the external JSON RPC connector needs a
|
{
"configurationType": "JsonRpc",
"config" : {
"baseUrl" : "https://customconnector.com/json-rpc",
"configuration" : {
"baseUrl": "https://mycms/store",
"token":"ljdadn234wqnadnn4"
}
}
}3.12.2. Features
This connector can support all features supported by the external connector it is configured to use. Please refer to the specific external connector documentation for its features and limitations.
3.13. OneDrive
OneDrive is a file hosting service, it allows users to store files as well as other personal data like Windows settings or BitLocker recovery keys in the cloud.
Version(s): we support the latest version of OneDrive.
3.13.1. Configuration
The OneDrive connector configuration consists of the following values:
| Parameter | Description |
|---|---|
The base URL of the OneDrive API. |
|
The URI where the user is redirected to after authorization is completed. |
|
The OneDrive application client id. Required when |
|
The OneDrive application secret. Required when |
|
A OneDrive OAuth2 token. When set, |
|
An OAuth2 refresh token. |
These values allow the OneDrive connector to authorize with OneDrive. You don’t have to provide all of these values, as this depends on the authentication flow you choose and on the way you design your application.
{
"configurationType": "OneDrive",
"config" : {
"redirectUri" : "https://xillio.com/callback",
"clientId" : "client-id",
"clientSecret" : "client-secret",
"refreshToken" : "fdb8fdbecf1d03ce5e6125c067733c0d51de209c"
}
}Your Application Refreshes the OneDrive Access Token
For this approach you will only put the access token in the Xillio API configuration and update the configuration whenever you get an authorization error later. In this case your configuration will look like this:
{
"configurationType": "OneDrive",
"name" : "My OneDrive",
"config": {
"token": "<your-token-here>"
}
}The Xillio API will use this token when communicating with OneDrive and you will get Authorization failed after the token expires.
The Xillio API Refreshes the OneDrive Access Token
For this approach you will have to provide the Xillio API with a refresh token, corresponding client ID, client secret and redirect URI. The Xillio API will then ask OneDrive for a new access token before each request. In this case your configuration will look like this:
{
"configurationType": "OneDrive",
"name" : "My OneDrive",
"config": {
"refreshToken": "<your-refresh-token-here>",
"clientId" : "<client-Id-of-your-application>",
"clientSecret" : "<client-secret-of-your-application>",
"redirectUri" : "<your-redirect-uri>"
}
}
It is important to not set a value for the token field in this type of OneDrive configuration.
|
As long as the refresh token is valid, the Xillio API will be generating a new access token for each request and use it when communicating with OneDrive. After the refresh token expires you will get Authorization failed.
OneDrive Authorization
The OneDrive API uses the standard OAuth 2.0 authorization framework to authorize apps and generate access tokens. This means that you are required to register your application with Microsoft to generate access tokens. Xillio API needs such an access token to request files, folders or content from OneDrive.
Register Your Application
The first step is to register your application with Microsoft and provide some details about your application. You can register your application in Microsoft Application Registration Portal.
| As of May 2019 this registration portal will no longer be supported and the following method of obtaining tokens might no longer be valid. It is recommended to use the authorization method with Azure AD v2.0. |
Sign Users In
Your application must initiate the sign-in process by contacting the Azure Active Directory authorization endpoint with a specified scope. The flow follows standard OAuth 2.0 authorization flows and requires calls from a web browser or web-browser control. The result of the authorization flow will return an access token and optionally other values which your application will provide to Xillio API through configuration.
Authentication Scopes
Scopes determine what type of access the application is granted when the user is signed in. All scopes support single sign-on on the web, which means that if a user is already signed in to OneDrive, then the user can skip the authentication flow and go straight to the authorization flow.
| Scope name | Description |
|---|---|
|
Enables your application to work offline even when the user isn’t active. Requires the use of code-flow. |
|
Grants read-only permission to all of a user’s OneDrive files. |
|
Grants read-only permission to all of a user’s OneDrive files, including files shared with the user. |
|
Grants read and write permission to all of a user’s OneDrive files. |
|
Grants read and write permission to all of a user’s OneDrive files, including files shared with the user. |
As an example, a typical application might request the following scopes:
files.readwrite offline_access
Supported Authentication Flows
Token flow
The most straightforward authorization flow is the token flow. This flow is useful for quickly obtaining an access token in an interactive fashion. This flow does not provide a refresh token, and therefore is not a good fit for long term access to resources.
To start the sign-in process with the token flow, use a web browser or web-browser control to load a URL request.
GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={client_id}&scope={scope}&response_type=token&redirect_uri={redirect_uri}| Parameter name | Description |
|---|---|
client_id |
The client ID of your application registered with Microsoft. |
redirect_uri |
The redirect URL that the browser is sent to when authentication is complete. |
response_type |
The type of response expected from the authorization flow. For this flow, the value must be |
scope |
A space-separated list of scopes your application requires. Don’t forget to encode your URL. |
Upon successful authentication and authorization of your application, the web browser is redirected to the redirect URL provided with additional parameters added to the URL.
https://localhost/myapp/auth-redirect#access_token=EwC...EB&authentication_token=eyJ...3EM&token_type=bearer&expires_in=3600&scope=onedrive.readwrite&user_id=3626...1d
The value of access_token is what you will have to put into Xillio API configuration to access OneDrive.
Code flow
The code flow for authentication is a three-step process with separate calls to authenticate and authorize the application and to generate an access token to access OneDrive. This also allows your application to receive a refresh token that will enable long-term use of OneDrive access in some scenarios, to allow access when the user isn’t actively using your application.
Step 1. Get an authorization code
To start the sign-in process with the code flow, use a web browser or web-browser control to load this URL request.
GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={client_id}&scope={scope}&response_type=code&redirect_uri={redirect_uri}
| Parameter name | Description |
|---|---|
client_id |
The client ID of your application registered with Microsoft. |
scope |
A space-separated list of scopes your application requires. Don’t forget to encode your URL. |
response_type |
The type of response expected from the authorization flow. For this flow, the value must be |
redirect_uri |
The redirect URL that the browser is sent to when authentication is complete. |
Upon successful authentication and authorization of your application, the web browser will be redirected to your redirect URL with additional parameters added to the URL.
https://localhost/myapp/auth-redirect?code=df6aa589-1080-b241-b410-c4dff65dbf7c
Step 2. Redeem the code for access tokens
After you have received the code value, you can redeem this code for a set of tokens that allow you to authenticate with OneDrive. To redeem the code, make the following request:
POST https://login.microsoftonline.com/common/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}&code={code}&grant_type=authorization_codeThe request body is a properly encoded URL string.
| Parameter name | Description |
|---|---|
client_id |
The client ID of your application registered with Microsoft. |
redirect_uri |
The redirect URL that the browser is sent to when authentication is complete. This should match the redirect_uri in the first request. For web apps, the domain portion of the redirect URI must match the domain portion of the redirect URI that you specified in the Microsoft Developer Center. |
client_secret |
The client secret of your application registered with Microsoft. |
code |
The authorization code you received in the first authentication request. |
If the call is successful, the response for the POST request contains a JSON string
that includes several properties, including access_token, token_type,
and refresh_token (if you requested the offline_access scope).
{
"token_type":"bearer",
"expires_in": 3600,
"scope":"wl.basic onedrive.readwrite",
"access_token":"EwCo...AA==",
"refresh_token":"eyJh...9323"
}The access token is valid for the number of seconds that is specified in the expires_in property. You can request a new access token by using the refresh token (if available), or by repeating the authentication request from the beginning.
Step 3. Get a new access token or refresh token
If your application has requested the offline_access scope this step will return a refresh_token that can be used to generate additional access tokens after the initial token has expired.
To redeem the refresh token for a new access token, make the following request:
POST https://login.microsoftonline.com/common/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id={client_id}&redirect_uri={redirect_uri}&client_secret={client_secret}&refresh_token={refresh_token}&grant_type=refresh_token
The request body is a properly encoded URL string, with some required parameters.
| Parameter name | Description |
|---|---|
client_id |
The client ID of your application registered with Microsoft. |
redirect_uri |
The redirect URL that the browser is sent to when authentication is complete. This should match the |
client_secret |
The client secret of your application registered with Microsoft. |
refresh_token |
The refresh token you received previously. |
If the call is successful, the response for the POST request contains a JSON string
that includes several properties including access_token, authentication_token and
refresh_token if you requested the offline_access scope.
{
"token_type":"bearer",
"expires_in": 3600,
"scope": "basic onedrive.readwrite offline_access",
"access_token":"EwCo...AA==",
"refresh_token":"eyJh...9323"
}The access token is valid for the number of seconds that is specified in the expires_in property. You can request a new access token by using the refresh token (if available) or by repeating the authentication request from the beginning.
| Refresh token for "Personal" OneDrive lasts for several months and can be used multiple times. |
OneDrive Authorization with Azure AD v2.0
This method uses the standard OAuth 2.0 authorization framework to authorize apps. It involves registering your application in the Azure Active Directory and sending HTTP requests to obtain and maintain tokens.
Register your application
As a prerequisite, you will need to register your application in the Azure portal. Go to the Azure Active Directory service, then under Application registrations (Preview) use the New Registration button.
In the registration form, it is recommended to select the account type that supports Microsoft personal accounts, see Features and Limitations.
The Redirect URI field in the registration form is marked optional, but it is actually required by the supported authorization flows.
After completing the registration, your application will be assigned Application (client) ID. For the code flow you will also need to generate a client secret in the Certifications & Secrets tab.
Auth Scopes
Part of an authorization flow is dynamically requesting specific permissions which are defined as scopes. In the following table, there are examples of scopes your application might require.
| Scope name | Description |
|---|---|
|
Enables your application to work offline even when the user isn’t active. Requires the use of the code flow. |
|
Grants read-only permission to all of a user’s OneDrive files. |
|
Grants read-only permission to all of a user’s OneDrive files, including files shared with the user. |
|
Grants read and write permission to all of a user’s OneDrive files. |
|
Grants read and write permission to all of a user’s OneDrive files, including files shared with the user. |
All these scopes, except offline_access, need to be prepended with the Microsoft Graph URI: https://graph.microsoft.com/.
An example of what scopes a typical application might request:
offline_access https://graph.microsoft.com/Files.ReadWrite
For more detailed information about scopes, please refer to Microsoft documentation.
Supported flows
Implicit grant flow
This flow can be used as a simple way of generating a short-lived access token in one step. It does not generate a refresh token.
Issuing tokens through the implicit grant flow needs to be allowed in the Azure portal. To do so:
-
Go to the Azure Active Directory service.
-
In the left-hand menu select Application Registration (Preview) and select your application.
-
In the left-hand menu select the Authentication tab and scroll down to Implicit grant under Advanced settings.
-
Check the
Access tokensbox and save.
To start the sign-in process with the implicit grant flow, browse to a URL like in the following example:
// Line breaks for legibility only
https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=https%3A%2F%2Fgraph.microsoft.com%2FFiles.ReadWrite
| Parameter name | Description |
|---|---|
client_id |
The Application (client) ID in the Azure portal, as assigned after the registration of your app. |
redirect_uri |
The redirect URI of your app where authentication responses can be sent to and received by your app. This URI must be a URL encoded version of a redirect URI registered in the portal. |
scope |
A space separated list of scopes your application requires. The |
Upon successful authentication and authorization of your application, you will be redirected to your redirect URI with additional parameters.
Example:
// Line breaks for legibility only
https://localhost/myapp/
#access_token=EwBoA8l6BAAU...
&token_type=bearer
&expires_in=3600
&scope=https://graph.microsoft.com/Files.ReadWrite
| There are other ways to use the implicit grant flow which are omitted here for the sake of brevity. For more information, please refer to the Microsoft documentation. |
Code flow
The code flow is a three-step process with separate calls to authenticate and authorize the application and to generate an access token. This flow also allows you to receive a refresh token used for retrieving access tokens. Using this flow enables you to let Xillio API take care of refreshing access tokens.
Step 1. Request authorization code
The authorization code flow begins with the client directing the user to the /authorize endpoint. In this request, the client indicates the permissions it needs to acquire from the user.
To start the sign-in process with the code flow, browse to a URL like in the following example:
// Line breaks for legibility only
https://login.microsoftonline.com/common/oauth2/v2.0/authorize?
client_id=49d21bd5-bab5-4bfa-8931-88feff5232f2
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=offline_access%20https%3A%2F%2Fgraph.microsoft.com%2FFiles.ReadWrite
| The request can have optional parameters, which are omitted here for the sake of brevity. For more information, please refer to the Microsoft documentation. |
| Parameter name | Description |
|---|---|
client_id |
The Application (client) ID in the Azure portal, as assigned after the registration of your app. |
redirect_uri |
The redirect URI of your app where authentication responses can be sent to and received by your app. This URI must be a URL encoded version of a redirect URI registered in the portal. |
scope |
A space separated list of scopes your application requires. |
Upon successful authentication and authorization of your application, the web browser will be redirected to your redirect URL with additional parameters depending on the optional parameters used.
Example:
https://localhost/myapp/?code=M6d343679-6cfb-5bb5-6141-56bba9b2eccc
The value of the code parameter is needed in the following step.
Step 2. Request an access token
Now that you’ve acquired an authorization code and have been granted permission by the user, you can redeem the code for an access_token to the desired resource. To do so, send a POST request to the /token endpoint like in the following example:
// Line breaks for legibility only POST /common/oauth2/v2.0/token HTTP/1.1 Host: https://login.microsoftonline.com Content-Type: application/x-www-form-urlencoded client_id=49d21bd5-bab5-4bfa-8931-88feff5232f2 &scope=offline_access%20https%3A%2F%2Fgraph.microsoft.com%2FFiles.ReadWrite &code=M976d709d-e045-254a-b650-cf666dfab743 &redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F &grant_type=authorization_code &client_secret=JqQX2PNo9bpM0uEihUPzyrh
| Parameter name | Description |
|---|---|
client_id |
The Application (client) ID in the Azure portal, as assigned after the registration of your app. |
scope |
Space separated list of requested scopes. Needs to match or be a subset of the list in the first step. |
code |
The authorization code you received in the first authentication request. |
redirect_uri |
The same redirect_uri value that was used to acquire the authorization code. |
client_secret |
The application secret that you created in the app registration portal for your app. |
The request body needs to be URL encoded.
A successful token response will contain a JSON body with an access_token. A refresh_token will be present if offline_access scope was requested. For example:
{
"token_type": "Bearer",
"scope": "https://graph.microsoft.com/Files.ReadWrite",
"expires_in": 3600,
"access_token": "EwBgA8l6BAAURSN...",
"refresh_token": "MCdNsmNMveqITy..."
}The expires_in indicates the amount of seconds for which access token is valid. A new pair of access and refresh tokens can be obtained by repeating the previous two steps or by using the refresh token in step 3.
| By default, refresh tokens are only revoked after 90 days of inactivity. This behavior can be configured. For more information, please refer to the Microsoft documentation. |
Step 3. Refresh an access token
If you provide a valid refresh token in the configuration, Xillio API takes care of this step, see configuration option with refresh token.
You can refresh an access token by issuing another POST request similar to the one in step 2.
Example request:
// Line breaks for legibility only POST /common/oauth2/v2.0/token HTTP/1.1 Host: https://login.microsoftonline.com Content-Type: application/x-www-form-urlencoded client_id=6731de76-14a6-49ae-97bc-6eba6914391e &scope=offline_access%20https%3A%2F%2Fgraph.microsoft.com%2FFiles.ReadWrite &refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq... &redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F &grant_type=refresh_token &client_secret=JqQX2PNo9bpM0uEihUPzyrh
| Parameter name | Description |
|---|---|
client_id |
The Application (client) ID in the Azure portal, as assigned after the registration of your app. |
scope |
Space separated list of requested scopes. Needs to match or be a subset of the list in the first step. |
refresh_token |
The refresh_token that you acquired in the second step of the flow. |
redirect_uri |
The redirect URI of your app where authentication responses can be sent to and received by your app. This URI must be a URL encoded version of a redirect URI registered in the portal. |
client_secret |
The application secret that you created in the app registration portal for your app. |
The request body needs to be URL encoded.
A successful token response will contain a JSON body with a new access and refresh token. For example:
{
"token_type": "Bearer",
"scope": "https://graph.microsoft.com/Files.ReadWrite",
"expires_in": 3600,
"access_token": "EwBoA8l6BAAURSN...",
"refresh_token": "MCaa5HRMEOA8HS..."
}| Refresh tokens are not revoked when used to acquire new access tokens. By default, refresh tokens are only revoked after 90 days of inactivity. This behavior can be configured. For more information, please refer to the Microsoft documentation. |
3.13.2. Features and Limitations
The OneDrive connector is designed to connect to personal OneDrive accounts only. However, it should be able to read entities and content of OneDrive business accounts.
The connector does not provide access to:
-
"Shared Items": files and folders that have been shared with the owner of the Drive
-
OneNote notebooks
Versioning
The connector does not allow to delete a specific version of an entity because the Microsoft Graph API for OneDrive personal does not support it.
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|
||
|
3.13.3. Mappings
These are the decorators that are set for certain types in OneDrive.
Entities retrieved via OneDrive can be of kind File or Folder.
| Decorator | Used By | Read-only | Field in OneDrive | Description |
|---|---|---|---|---|
|
|
True |
Always True |
This decorator is only set for folders, and |
|
||||
|
|
True |
|
Date and time when the requested entity was created. |
|
|
True |
|
Name of the user that created the requested entity. |
|
|
False |
|
Description associated in OneDrive with the requested entity. |
|
|
True (update Name decorator to change extension) |
Computed from |
The extension of the requested file, or an empty string if it has none. |
|
|
True (update Name decorator to change extension) |
Computed from |
The sanitized extension of the requested file. |
|
|
True |
|
The size in bytes of the requested file. |
|
|
True |
Computed from |
The path to the requested entity relative to the OneDrive root. |
|
||||
|
|
True |
|
The |
|
|
True |
|
The |
|
|
True |
|
The mime type of the requested file. This is determined by logic in OneDrive and might not be the value provided when the file was uploaded. |
|
|
True |
|
Last modified date and time of the requested entity. |
|
|
True |
|
Name of the user that modified the requested entity as last. |
|
|
True |
|
The name of the requested entity. |
|
|
False (update this decorator to rename entity or change file’s extension) |
|
The name of the requested entity. |
|
|
False (update this decorator to move entity to new location) |
Computed from |
The XDIP of the parent entity. |
|
|
True |
|
URL that can display the requested entity in the browser. |
|
|
True |
|
The current verrsion id of the file. |
3.14. Opentext
Version(s): we support version 16.2 of Opentext Content Server.
3.14.1. Configuration
The configuration for the Opentext connector consists of the following parameters:
| Parameter | Description |
|---|---|
The full URL of the OpenText Content Server API extension: server, port and the path to the API root. |
|
The username of an account on OpenText. |
|
The password of the account. |
|
The id of the root node. Default: |
|
The number of attempts to get an authentication ticket from Opentext Content Server. Default: |
|
Base number of seconds to wait between the first and second authentication attempt. This will be doubled for every following attempt. Default: |
|
OpenText Content Server authentication ticket. |
The optional rootNode parameter is the id of the root node of the OpenText workspace you want to access.
Its default value is 2000, as it is the common id of the root of the Enterprise workspace. It can however differ across Content Server instances, in which case you need to specify it.
The parameter ticket is used internally by the connector to persist the Opentext authentication ticket and reuse it as long as it is valid. This approach restricts requests to Opentext API authentication endpoint to minimum. You can leave it empty when creating or updating configurations.
You can configure Opentext connector to retry getting Content Server authentication ticket if the first attempt fails. By default, the connector will try to get the authentication ticket three times. The delay between the first and second attempt is configurable. For all the following attempts the connector will always double the previous delay. For example, with the default value of two seconds base delay, the connector will wait four seconds between the second and third attempt and eight seconds between the third and fourth attempt.
{
"configurationType": "Opentext",
"config" : {
"baseUrl" : "http://otcs.xillio.com:8080/otcs/cs.exe",
"username" : "username",
"password" : "password"
}
}3.14.2. Features and Limitations
-
Some content types can be created (e.g. 0 =
Folderand 144 =Document), some cannot (e.g. 356 =Blog) -
Special characters in queries must be escaped manually.
-
The content types discovery (/types endpoint) requires read-write access to the node on which the Opentext API call is performed. Our connector uses by default the root node from the configuration, but you can redirect it to a different node by assigning the nickname "xillio_content_type_discovery_node" to this node.
-
This connector supports pagination when requesting a list of children of the folders. But to not lower the performance of the connector only those combinations of offset and limit are supported when the offset is a multiple of limit. Also be aware of the configuration of the Opentext server you are connecting to. It can limit the size of the page. By default this limitation is 100 items.
Named Queries
Opentext uses LQL (livelink query language), more information on how to create queries in LQL can be found in your Opentext instance.
Example: Search by filename
The following request creates a query that will return entities where their name contains the provided string.
$ curl -X POST \
https://demo-tenant.xill.io/v2/configurations/<<OPENTEXT_CONFIGURATION_ID>>/queries \
-H 'Authorization: bearer <<AUTH_TOKEN>>' \
-H 'Content-Type: application/json' \
-d '{
"name":"SearchFileByName",
"template":"OTName:\"${q_name}\""
}'We can then query the target repository for files containing the string Test:
$ curl -X GET \
'https://demo-tenant.xill.io/v2/queries/<<OPENTEXT_CONFIGURATION_ID>>/SearchFileByName?scope=entities&q_name=Test' \
-H 'Authorization: bearer <<AUTH_TOKEN>>' \
-H 'Content-Type: application/json' \The result of the previous call will be something similar to (omitting irrelevant information by …):
{
"entities": [
{
"id": "https://demo-tenant.xill.io/v2/entities/8a80cb81660b9d8f01660ba03fd00002/6514",
"xdip": "xdip://8a80cb81660b9d8f01660ba03fd00002/6514",
"kind": "Document",
"original": {
... ,
"name": {
"systemName": "TestFile.jpg",
"displayName": "TestFile.jpg"
},
...
},
"modified": {
...
}
},
...
]
}Example: Search by modified since
The following requests creates a query that will only return entities that were created before the specified date.
$ curl -X POST \
https://demo-tenant.xill.io/v2/configurations/<<OPENTEXT_CONFIGURATION_ID>>/queries \
-H 'Authorization: bearer <<AUTH_TOKEN>>' \
-H 'Content-Type: application/json' \
-d '{
"name":"SearchByModifiedSince",
"template":"OTModifyDate:(>\"${q_date\"})"
}'The following request uses the created query to return entities from OpenText that have been modified after 17-07-2018.
$ curl -X GET \
'https://demo-tenant.xill.io/v2/queries/<<OPENTEXT_CONFIGURATION_ID>>/SearchByModifiedSince?scope=entities&q_date=20180717' \
-H 'Authorization: bearer <<AUTH_TOKEN>>' \
-H 'Content-Type: application/json' \The result of the previous call will be something similar to (omitting irrelevant information by …):
{
"entities": [
{
"id": "https://demo-tenant.xill.io/v2/entities/8a80cb81660b9d8f01660ba03fd00002/30365",
"xdip": "xdip://8a80cb81660b9d8f01660ba03fd00002/30365",
"kind": "Folder",
"original": {
...,
"modified": {
"date": "2018-09-12T09:05:25.000+02:00",
"by": {
"displayName": "1000",
"systemName": "1000"
}
},
...
},
"modified" : {
...
}
},
...
]
}Example: Search in contents
The following requests creates a query that will only return entities where a certain text can be found in the contents.
$ curl -X POST \
https://demo-tenant.xill.io/v2/configurations/<<OPENTEXT_CONFIGURATION_ID>>/queries \
-H 'Authorization: bearer <<AUTH_TOKEN>>' \
-H 'Content-Type: application/json' \
-d '{
"name":"SearchByContents",
"template":"OTData:\"${q_text}\""
}'The following request uses the created query to return entities from OpenText that have "test" in their contents.
$ curl -X GET \
'https://demo-tenant.xill.io/v2/queries/<<OPENTEXT_CONFIGURATION_ID>>/SearchByContents?scope=entities&q_text=test' \
-H 'Authorization: bearer <<AUTH_TOKEN>>' \
-H 'Content-Type: application/json' \The result of the previous call will be something similar to (omitting irrelevant information by …):
{
"entities": [
{
"id": "https://demo-tenant.xill.io/v2/entities/8a80cb81660b9d8f01660ba03fd00002/16573",
"xdip": "xdip://8a80cb81660b9d8f01660ba03fd00002/16573",
"kind": "Document",
"original": {
...,
"name": {
"systemName": "FileContainingTestData.txt",
"displayName": "FileContainingTestData.txt"
},
...
},
"modified" : {
...
}
},
...
]
}Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|
||
|
3.14.3. Mappings
| Decorator | Used By | Field in Opentext | Description |
|---|---|---|---|
|
|
|
Whether the entity has children. |
|
All entities |
|
The ID of content type. |
|
All entities |
|
The name of content type. |
|
All entities |
|
The time the entity was created. |
|
All entities |
|
The id of the user who has created the entity. |
|
All entities except when retrieved using a query |
|
The display name of the user who has created the entity. |
|
All entities except when retrieved using a query |
|
The email of the user who has created the entity. |
|
All entities |
|
The description of the entity as displayed in Opentext. |
|
|
Computed from |
The extension of the document as derived from the name. |
|
|
|
The size of the document in bytes. |
|
|
|
The mime type of the requested document. |
|
All entities |
|
The time the entity was last modified. |
|
All entities except when retrieving versions |
|
The id of the user who has last modified the entity. |
|
All entities except when retrieved using a query or when retrieving versions. |
|
The display name of the user who has last modified the entity. |
|
All entities except when retrieved using a query or when retrieving versions. |
|
The email of the user who has created the entity. |
|
All entities |
|
The name of the entity that is displayed in Opentext. |
|
All entities |
|
The XDIP of the parent entity. |
|
|
|
The number indicating what version of the |
3.14.4. RPC Endpoints
This connector supports RPC for Records Management metadata.
categories
The categories namespace can extract information about category definitions within OpenText.
To get the list of categories, use the API endpoint /templates.
categories/getCategoryAttributes
Returns the list of the attributes of the specific Opentext category.
POST /v2/rpc/{configurationId}/categories/getCategoryAttributes
------
HTTP/1.1 200 OK
Content-Type: application/json
Input |
Type |
Default |
Description |
|
|
The id of the category. |
Returns CategoryAttribute[]: the list of the attributes of the specific Opentext category.
Path |
Type |
Description |
|
the list of the attributes of the specific Opentext category |
[ {
"id" : 3,
"name" : "Extra number",
"required" : false,
"type" : 2
} ]members
The members namespace can extract information about members (users or groups) within OpenText.
members/getMember
Returns details about the member (user or group) with the ID id.
POST /v2/rpc/{configurationId}/members/getMember
------
HTTP/1.1 200 OK
Content-Type: application/json
Input |
Type |
Default |
Description |
|
|
The id of the member. |
Returns Member: the details about the member (user or group).
Path |
Type |
Description |
|
|
The name of the member. |
|
|
The flag whether the member is deleted. |
|
|
The email of the member. |
|
|
The member’s type (i.e. user or group). |
|
|
The first name of the member. |
|
|
The last name of the member. |
{
"typeName" : "User",
"name" : "John Doe",
"firstName" : "John",
"lastName" : "Doe",
"businessEmail" : "john.doe@your-company.com",
"deleted" : false
}nodes
The nodes namespace can extract information from nodes within OpenText.
A 404 - Not Found with a NoSuchEntity error can be thrown when either the provided node does not exist
or when the endpoint is not accessible due to, for example, a module as Records Management is not installed.
nodes/assignCategory
Assigns an existing category to an existing node.
POST /v2/rpc/{configurationId}/nodes/assignCategory
------
HTTP/1.1 204 No Content
Input |
Type |
Default |
Description |
|
|
The id of the node. |
|
|
|
The id of the category. |
nodes/createRMClassification
Adds a new classification to the node with ID id.
POST /v2/rpc/{configurationId}/nodes/createRMClassification
------
HTTP/1.1 200 OK
Content-Type: application/json
Input |
Type |
Default |
Description |
|
|
The id of the node. |
|
|
|
The id of the classification. |
|
|
|
|
The optional status for the classification of the node. |
|
|
|
The optional status date for the classification of the node. |
Returns RMClassificationResponse: the classifications of the node.
Path |
Type |
Description |
|
The definitions of the Records Management classifications data. |
|
|
The Records Management classifications data. |
{
"data" : [ {
"name" : "Master documents",
"rmclassificationId" : 59,
"type" : 3,
"fileNumber" : "10.8.54",
"statusDate" : "2019-08-22T00:00:00",
"status" : "5",
"recordDate" : "2019-08-12T00:00:00",
"recordType" : 31549,
"establishment" : "Example company",
"addressee" : "Company",
"accession" : "ACCESSION-CODE-5",
"originator" : "HR Department",
"sentTo" : "External",
"lastReviewDate" : "2019-08-22T00:00:00",
"nextReviewDate" : "2019-09-22T00:00:00",
"subject" : "Quick start guide",
"official" : false,
"essential" : "ESSENTIAL-CODE-1",
"storage" : "Hard disk",
"cyclePeriod" : 1,
"receivedDate" : "2019-08-14T00:00:00",
"primary" : true
} ],
"definitions" : {
"fileNumber" : {
"validValues" : [ "1", "2" ],
"validValuesName" : [ "1..Confidential", "2..Public" ],
"type" : 2,
"name" : "Security Clearance Level",
"key" : "clearance_level",
"description" : "The security clearance of a record",
"required" : true
},
"status" : {
"validValues" : [ "1", "2" ],
"validValuesName" : [ "1..Confidential", "2..Public" ],
"type" : 2,
"name" : "Security Clearance Level",
"key" : "clearance_level",
"description" : "The security clearance of a record",
"required" : true
}
}
}nodes/createXRef
Adds a new cross-reference to the node with ID id to reference another node.
POST /v2/rpc/{configurationId}/nodes/createXRef
------
HTTP/1.1 200 OK
Content-Type: application/json
Input |
Type |
Default |
Description |
|
|
The id of the node. |
|
|
|
The ID of the node referenced. |
|
|
|
The cross-reference type. |
|
|
|
The comment for the cross-reference. |
Returns XRefResponse: the cross-references of the node.
Path |
Type |
Description |
|
The definitions of the cross-references data. |
|
|
The cross-references data. |
{
"data" : [ {
"xrefId" : 4659,
"type" : 144,
"name" : "graph.png",
"xrefType" : "ASSETSTORAGEPERSPECTIVE",
"verNum" : 0,
"mimeType" : "image/png",
"relatedCode" : "ASSETSTORAGEPERSPECTIVEFOLDER",
"location" : "Enterprise",
"comment" : "Original image for graph"
} ],
"definitions" : {
"relatedCode" : {
"validValues" : [ "1", "2" ],
"validValuesName" : [ "1..Confidential", "2..Public" ],
"type" : 2,
"name" : "Security Clearance Level",
"key" : "clearance_level",
"description" : "The security clearance of a record",
"required" : true
},
"xrefType" : {
"validValues" : [ "1", "2" ],
"validValuesName" : [ "1..Confidential", "2..Public" ],
"type" : 2,
"name" : "Security Clearance Level",
"key" : "clearance_level",
"description" : "The security clearance of a record",
"required" : true
}
}
}nodes/deleteRMClassification
Removes the classification with ID classificationId from the node with ID id.
POST /v2/rpc/{configurationId}/nodes/deleteRMClassification
------
HTTP/1.1 204 No Content
Input |
Type |
Default |
Description |
|
|
The id of the node. |
|
|
|
The id of the classification. |
nodes/deleteXRef
Removes the reference with type xrefType from the node with ID id to node with ID
xrefId.
POST /v2/rpc/{configurationId}/nodes/deleteXRef
------
HTTP/1.1 204 No Content
Input |
Type |
Default |
Description |
|
|
The id of the node to remove a cross-reference from. |
|
|
|
The id of the referenced node to remove. |
|
|
|
The type of reference to remove. |
nodes/getCategories
Returns the categories of the node with ID id.
POST /v2/rpc/{configurationId}/nodes/getCategories
------
HTTP/1.1 200 OK
Content-Type: application/json
Input |
Type |
Default |
Description |
|
|
The id of the node. |
Returns OpentextNodeCategoriesInfo[]: the categories of the node.
Path |
Type |
Description |
|
the categories of the node |
[ {
"id" : 1234,
"name" : "Category A"
} ]nodes/getCategoryFields
Returns the fields of the selected category.
POST /v2/rpc/{configurationId}/nodes/getCategoryFields
------
HTTP/1.1 200 OK
Content-Type: application/json
Input |
Type |
Default |
Description |
|
|
The id of the node. |
|
|
|
The id of the category. |
Returns CategoryFieldDefinition[]: the fields of the category.
Path |
Type |
Description |
|
the fields of the category |
[ {
"key" : "54117_2",
"name" : "Number of pages",
"type" : 2,
"persona" : "",
"required" : true,
"typeName" : "Integer",
"readOnly" : false,
"multiValue" : false
} ]nodes/getRMClassifications
Returns the classifications of the node with ID id.
POST /v2/rpc/{configurationId}/nodes/getRMClassifications
------
HTTP/1.1 200 OK
Content-Type: application/json
Input |
Type |
Default |
Description |
|
|
The id of the node. |
Returns RMClassificationResponse: the classifications of the node.
Path |
Type |
Description |
|
The definitions of the Records Management classifications data. |
|
|
The Records Management classifications data. |
{
"data" : [ {
"name" : "Master documents",
"rmclassificationId" : 59,
"type" : 3,
"fileNumber" : "10.8.54",
"statusDate" : "2019-08-22T00:00:00",
"status" : "5",
"recordDate" : "2019-08-12T00:00:00",
"recordType" : 31549,
"establishment" : "Example company",
"addressee" : "Company",
"accession" : "ACCESSION-CODE-5",
"originator" : "HR Department",
"sentTo" : "External",
"lastReviewDate" : "2019-08-22T00:00:00",
"nextReviewDate" : "2019-09-22T00:00:00",
"subject" : "Quick start guide",
"official" : false,
"essential" : "ESSENTIAL-CODE-1",
"storage" : "Hard disk",
"cyclePeriod" : 1,
"receivedDate" : "2019-08-14T00:00:00",
"primary" : true
} ],
"definitions" : {
"fileNumber" : {
"validValues" : [ "1", "2" ],
"validValuesName" : [ "1..Confidential", "2..Public" ],
"type" : 2,
"name" : "Security Clearance Level",
"key" : "clearance_level",
"description" : "The security clearance of a record",
"required" : true
},
"status" : {
"validValues" : [ "1", "2" ],
"validValuesName" : [ "1..Confidential", "2..Public" ],
"type" : 2,
"name" : "Security Clearance Level",
"key" : "clearance_level",
"description" : "The security clearance of a record",
"required" : true
}
}
}nodes/getSecurityClearance
Returns the current security clearance of the node with ID id.
POST /v2/rpc/{configurationId}/nodes/getSecurityClearance
------
HTTP/1.1 200 OK
Content-Type: application/json
Input |
Type |
Default |
Description |
|
|
The id of the node. |
Returns SecurityClearanceResponse: the current security clearance.
Path |
Type |
Description |
|
The definitions of the security clearance data. |
|
|
The security clearance data. |
{
"data" : {
"clearanceLevel" : 1,
"supplementalMarkings" : [ "PUBLIC" ],
"inheritFrom" : false
},
"definitions" : {
"clearanceLevel" : {
"validValues" : [ "1", "2" ],
"validValuesName" : [ "1..Confidential", "2..Public" ],
"type" : 2,
"name" : "Security Clearance Level",
"key" : "clearance_level",
"description" : "The security clearance of a record",
"required" : true
},
"supplementalMarkings" : {
"validValues" : [ "1", "2" ],
"validValuesName" : [ "1..Confidential", "2..Public" ],
"type" : 2,
"name" : "Security Clearance Level",
"key" : "clearance_level",
"description" : "The security clearance of a record",
"required" : true
}
}
}nodes/getXRefs
Returns the cross-references of the node with ID id.
POST /v2/rpc/{configurationId}/nodes/getXRefs
------
HTTP/1.1 200 OK
Content-Type: application/json
Input |
Type |
Default |
Description |
|
|
The id of the node. |
Returns XRefResponse: the cross-references.
Path |
Type |
Description |
|
The definitions of the cross-references data. |
|
|
The cross-references data. |
{
"data" : [ {
"xrefId" : 4659,
"type" : 144,
"name" : "graph.png",
"xrefType" : "ASSETSTORAGEPERSPECTIVE",
"verNum" : 0,
"mimeType" : "image/png",
"relatedCode" : "ASSETSTORAGEPERSPECTIVEFOLDER",
"location" : "Enterprise",
"comment" : "Original image for graph"
} ],
"definitions" : {
"relatedCode" : {
"validValues" : [ "1", "2" ],
"validValuesName" : [ "1..Confidential", "2..Public" ],
"type" : 2,
"name" : "Security Clearance Level",
"key" : "clearance_level",
"description" : "The security clearance of a record",
"required" : true
},
"xrefType" : {
"validValues" : [ "1", "2" ],
"validValuesName" : [ "1..Confidential", "2..Public" ],
"type" : 2,
"name" : "Security Clearance Level",
"key" : "clearance_level",
"description" : "The security clearance of a record",
"required" : true
}
}
}nodes/updateCategory
Updates field of node’s category.
POST /v2/rpc/{configurationId}/nodes/updateCategory
------
HTTP/1.1 204 No Content
Input |
Type |
Default |
Description |
|
|
The id of the node. |
|
|
|
The id of the category. |
|
|
|
The key of the field to update. |
|
|
|
The new value of the field. |
nodes/updateRMClassification
Updates a classification for the node with ID id.
OpenText only allows updating the classificationId when other fields (such as
status and statusDate) are not present. Note that updating the
classificationId might remove metadata from the fields of the classification (such as
status and statusDate) and default them to the system default.
|
POST /v2/rpc/{configurationId}/nodes/updateRMClassification
------
HTTP/1.1 200 OK
Content-Type: application/json
Input |
Type |
Default |
Description |
|
|
The id of the node. |
|
|
|
`` |
The optional id of the new classification. |
|
|
|
The optional new status of the classification. |
|
|
|
The optional new date for the status. |
Returns RMClassificationResponse: the classifications of the node.
Path |
Type |
Description |
|
The definitions of the Records Management classifications data. |
|
|
The Records Management classifications data. |
{
"data" : [ {
"name" : "Master documents",
"rmclassificationId" : 59,
"type" : 3,
"fileNumber" : "10.8.54",
"statusDate" : "2019-08-22T00:00:00",
"status" : "5",
"recordDate" : "2019-08-12T00:00:00",
"recordType" : 31549,
"establishment" : "Example company",
"addressee" : "Company",
"accession" : "ACCESSION-CODE-5",
"originator" : "HR Department",
"sentTo" : "External",
"lastReviewDate" : "2019-08-22T00:00:00",
"nextReviewDate" : "2019-09-22T00:00:00",
"subject" : "Quick start guide",
"official" : false,
"essential" : "ESSENTIAL-CODE-1",
"storage" : "Hard disk",
"cyclePeriod" : 1,
"receivedDate" : "2019-08-14T00:00:00",
"primary" : true
} ],
"definitions" : {
"fileNumber" : {
"validValues" : [ "1", "2" ],
"validValuesName" : [ "1..Confidential", "2..Public" ],
"type" : 2,
"name" : "Security Clearance Level",
"key" : "clearance_level",
"description" : "The security clearance of a record",
"required" : true
},
"status" : {
"validValues" : [ "1", "2" ],
"validValuesName" : [ "1..Confidential", "2..Public" ],
"type" : 2,
"name" : "Security Clearance Level",
"key" : "clearance_level",
"description" : "The security clearance of a record",
"required" : true
}
}
}3.14.5. RPC Models
CategoryAttribute
Holds the definition of an attribute of the Opentext category.
Field |
Type |
Description |
|
|
The flag whether value for this attribute will be required when assigning category to a node. |
|
|
The name of the attribute. |
|
|
The type of the attribute (internal Opentext ID of the type). |
|
|
The ID of the attributes. |
CategoryFieldDefinition
Definition of a field of OpenText category.
Field |
Type |
Description |
|
|
The key of the category field. |
|
|
The name of the field. |
|
|
The ID of the type of the field. |
|
|
The flag whether field is read-only. |
|
|
The flag whether field can hold multiple values. |
|
|
The indicator whether the field is member or user group reference. |
|
|
The name of the type of the field. |
|
|
The flag whether field is mandatory to fill. |
Definition
The definition for a model within OpenText.
This definition contains information about a certain piece of metadata within OpenText. The information could be for example, the name of the metadata, the system key, a description for this piece of metadata and its possible values.
Field |
Type |
Description |
|
|
The valid values for this definition. |
|
|
The system key for this definition. |
|
|
Whether this metadata field is required or not. |
|
|
The human readable name for this definition. |
|
|
|
|
|
The description for this definition. |
|
|
The human readable value names for this definition. |
Member
Holds values of certain user or group in Opentext instance.
Field |
Type |
Description |
|
|
The name of the member. |
|
|
The flag whether the member is deleted. |
|
|
The email of the member. |
|
|
The member’s type (i.e. user or group). |
|
|
The first name of the member. |
|
|
The last name of the member. |
OpentextNodeCategoriesInfo
Category information.
Field |
Type |
Description |
|
|
Name of the category. |
|
|
ID of the category. |
RMClassification
Records Management classification information for a node.
Field |
Type |
Description |
|
|
The cycle period for this classification. |
|
|
The received date for this classification. |
|
|
The subject information for this classification. |
|
|
The id of the classification. |
|
|
The name of the classification. |
|
|
The essential code for this classification. |
|
|
The author or originator of this classification. |
|
|
The status of this classification. |
|
|
The date at which this classification is next to be reviewed. |
|
|
Whether this classification is official or not. |
|
|
The record type value for this classification. |
|
|
The date at which the classification was last reviewed. |
|
|
The accession code for this classification. |
|
|
The date where this node is recorded. |
|
|
The addressee(s) for this classification. |
|
|
The type ID of the classification. |
|
|
Whether this classification is the primary classification for this node. |
|
|
The last modified date for the status of this classification. |
|
|
The storage medium code for this classification. |
|
|
The originating organization for this classification. |
|
|
The file number for this classification. |
|
|
The other addressee(s) for this classification. |
RMClassificationDefinition
The definitions for Records Management classification metadata fields.
Field |
Type |
Description |
|
The definition for a status. |
|
|
The definition for a file number. |
RMClassificationResponse
The response for retrieving the Records Management classifications of a node.
Field |
Type |
Description |
|
The definitions of the Records Management classifications data. |
|
|
The Records Management classifications data. |
SecurityClearance
Security clearance information for a node.
Field |
Type |
Description |
|
|
|
|
|
Any supplemental markings for this clearance. |
|
|
The current clearance level. |
SecurityClearanceDefinition
The definitions for Security Clearance metadata fields.
Field |
Type |
Description |
|
The definition for a supplemental marking. |
|
|
The definition for a clearance level. |
SecurityClearanceResponse
The response for retrieving the security clearance of a node.
Field |
Type |
Description |
|
The definitions of the security clearance data. |
|
|
The security clearance data. |
XRef
Cross-reference information for one node to another node.
Field |
Type |
Description |
|
|
The location of the referenced node. |
|
|
The name of the node referenced. |
|
|
The mime-type of the referenced node. |
|
|
The type ID of the node referenced. |
|
|
The type of the reference from the other node. |
|
|
The type of the reference to the other node. |
|
|
A comment about this cross-reference. |
|
|
The ID of the node referenced. |
|
|
The version of the referenced node. |
XRefDefinition
The definitions for cross-reference metadata fields.
Field |
Type |
Description |
|
The definition for the related code. |
|
|
The definition for the cross-reference type. |
XRefResponse
The response for retrieving the cross-reference information of a node.
Field |
Type |
Description |
|
The definitions of the cross-references data. |
|
|
The cross-references data. |
3.15. S3
Simple Storage Service (S3) is an object storage service that offers industry-leading scalability, data availability, security, and performance.
Version(s): we support S3 APIs with AWS version 4 signatures.
|
This connector is primarily developed for AWS S3. Other S3 API implementations are supported if implemented correctly.
The connector might produce unexpected results due to small differences in functionality for these APIs. This is especially the case for error handling. |
3.15.1. Configuration
The S3 connector operates on a single bucket as is configured in the connector configuration. This bucket must be accessible through the internet for the provided accessKey and secretKey.
|
Newly created buckets:
It might take some time before the connector can connect to a newly created bucket, as the bucket is still being processed.
|
Connector Configuration
The S3 connector configuration consists of the following values:
| Parameter | Description |
|---|---|
The base URL to the target bucket. It must include the bucket name. |
|
The access key id to use for authentication. |
|
The secret access key to use for authentication. |
|
The region in which this bucket resides. Required for AWS S3 instances. |
|
The delimiter for traversing the bucket. See Hierarchy. Default: |
{
"configurationType": "S3",
"config" : {
"baseUrl" : "https://mybucket.s3.amazonaws.com",
"username" : "AKIAIOSFODNN7EXAMPLE",
"password" : "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
"region" : "eu-central-1"
}
}3.15.2. Features and Limitations
Currently, only retrieving object entities and binary content in unencrypted buckets is supported.
Hierarchy
Amazon S3 is a non-hierarchical key-value store. However, to ease the navigation with the Xillio API, you can set a "path delimiter". The default delimiter is /.
In a bucket containing the following keys:
- infrastructure-audit-jan
- infrastructure-audit-feb
- content-whitepaperif the delimiter is set to -, the Xillio API will expose the following hierarchy:
infrastructure-
|
├── audit-
| |
| ├── jan
| \── feb
|
\── content-
|
\── whitepaperIn this example, the entities infrastructure-, audit- and content- can be retrieved in the Xillio API, despite not corresponding to actual objects in Amazon S3. They are the prefixes of their respective sub-keys, and are considered the parents of those entites within the Xillio API. They have the content type Prefix.
To expose a bucket as a key-value store, set the empty string ("") as delimiter. Every entity will then reside in the root.
|
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|||
|
3.15.3. Mappings
| Decorator | Used By | Field in S3 | Description |
|---|---|---|---|
container.hasChildren |
All entities |
Whether the entity could have children. Is always set to true unless using an empty |
|
contentType.systemName |
All entities |
The content type of the entity. Either |
|
contentType.displayName |
All entities |
The content type of the entity. Either |
|
file.rawExtension |
All entities |
|
The extension of the requested |
file.extension |
All entities |
|
The sanitized extension of the requested |
file.size |
|
|
The size in bytes of the requested |
fileSystem.path |
All entities |
|
The filesystem representation of the |
hash.md5 |
|
|
The MD5 hash of this |
mimeType |
|
The |
|
modified.date |
|
|
The date in which the requested |
modified.by.displayName |
|
The |
|
modified.by.systemName |
|
|
The |
name.displayName |
All entities |
|
The name of this entity. The last part of the key as split by |
name.systemName |
All entities |
|
The name of this entity. The last part of the key as split by |
parent.id |
All entities |
|
The XDIP of the parent entity, as computed by using the 'Key' value of this entity. |
3.16. Salesforce
Salesforce is a complex CRM cloud-based solution. This connector exposes its knowledge base part called Salesforce Knowledge.
Version(s): we support Salesforce Classic and Lightning.
3.16.1. Configuration
Salesforce connector configuration
The Salesforce connector configuration consists of the URL of your Salesforce site and authentication credentials.
| Parameter | Description |
|---|---|
The base URL of the Salesforce API. Default: |
|
An OAuth2 refresh token. |
|
The client id. Required when |
|
The client secret. Required when |
|
An OAuth2 token. When set, |
{
"configurationType": "Salesforce",
"config" : {
"refreshToken" : "5Axc861F1.ndOFuBX057HR38ot4A7419...",
"clientId" : "3MFG96_7YM2sI9wTgZjGhoQXR6WBX35X...",
"clientSecret" : "FB5AE94E81B62A80692F4D9CUR63M890...",
"token" : "00A4p000000OtwS!AQNEPJgHxpEq9YXP..."
}
}Authenticating to Salesforce is done with an OAuth access token. You only need to provide some of the values depending on whether you want to have your application or the Xillio API to handle refreshing the access token.
Your Application Refreshes the Salesforce Access Token
For this approach, you only need to provide the base URL and the access token. Update the configuration whenever you get an authorization error later.
An example configuration might look like this:
{
"configurationType": "Salesforce",
"name" : "My Salesforce",
"config": {
"baseUrl": "https://eu26.salesforce.com",
"token": "00A4p000000OtwS!AQNEPJgHxp..."
}
}The Xillio API will use this token when communicating with Salesforce. After the token expires you will get an Authorization failed error.
The Xillio API Refreshes the Salesforce Access Token
For this approach, you need to provide the base URL, the refresh token and the corresponding client ID and client secret. Optionally you can provide an initial access token as well.
The Xillio API will then generate new access token whenever it receives a response from Salesforce indicating the current access token is expired.
An example configuration might look like this:
{
"configurationType": "Salesforce",
"name" : "My Salesforce",
"config": {
"baseUrl": "https://eu26.salesforce.com",
"refreshToken": "5Axc861F1.ndOFuBX057HR38ot4A74...",
"clientId" : "3MFG96_7YM2sI9wTgZjGhoQ6WBX35X...",
"clientSecret" : "FB5AE94E81B62A80692F4D9CUR63M890..."
}
}As long as the refresh token is valid, the Xillio API will be generating a new access token whenever necessary. After the refresh token expires you will get an Authorization failed error.
Salesforce Authorization
The Salesforce API uses the standard OAuth 2.0 authorization framework to authorize applications and generate access tokens.
You can find a simple description of how to set up OAuth with Salesforce in this article. For more detailed information, please refer to the resources here and here.
For registration of your application in Salesforce, please note that at least api, refresh_token, offline_access OAuth scopes are required for use with Xillio API.
3.16.2. Features and Limitations
This connector has read, write and translation functionality.
There is no custom metadata or search support.
The connected Salesforce instance is required to have Knowledge enabled with multilingual support.
Entity types and hierarchy
The connector exposes three types of Salesforce Knowledge entities: Category Groups, Categories and Articles; as well as two kinds of virtual folders.
Write operations are only supported for Article entities.
The following is an example of Salesforce as exposed by this connector. It organizes the entities in a tree structure:
\ | - Articles (1) | | - FAQ (2) | | | - How to do this? (3) | | \ - How to deal with that? | ... | | - Category group (4) | | - This category (5) | | \ - How to do this? | \ - The other category | \ - Subcategory | | - Non FAQ Article ... ...
The top level always contains a virtual folder Articles 1.
The Articles folder contains a virtual folder for each article type existing in the connected Salesforce instance.
These Article Type Folders 2 contain every Article 3 of the given type, including the uncategorized ones.
The other top-level entities are Category Groups 4.
Children of Category Groups are Categories 5.
Children of Categories are Other Categories or Articles.
Articles
Articles are the only entities for which write operations are supported.
Articles in Salesforce can have a publication status of draft, online or archived.
This connector exposes draft and online Articles, without any difference.
One Article in Salesforce can exist in both draft and online state, when it has been published and is in the process of being edited.
The online version of such articles cannot be updated or deleted, attempts to do so will result in Operation Not Allowed with the XDIP of the draft version in the message of the error.
Articles in Salesforce can have zero, one, or more Category assigned.
As exposed by this connector, Articles have their assigned Categories and their corresponding Type Folder displayed as parents in calls using path_parents_* scope. Additionally, the parent decorator always contains an id of one of those parents.
Creating an Article can be done using an XDIP of either an Article Type Folder or a Category.
The first option results in creating an uncategorized Article.
The other option results in creating an Article in the specified Category and requires filling the contentType.systemName with the desired type of the Article to be created.
All the available Article types of the connected Salesforce instance can be obtained by calling the /types endpoint.
Articles are always created in draft state.
Changing the Category parents of an Article is done by updating the parent decorator as described by the following table:
id filled in original.parent |
id filled in modified.parent |
Category assignment |
|---|---|---|
Added. |
||
Removed. |
||
Removed and added, if the values differ. |
Articles in Salesforce can have a customized layout assigned to them which can define various custom fields.
This connector exposes the names and values of these fields as binary content. Requesting the binary content of an Article entity returns a JSON similar to the one in the following example:
{
"additional_text__c": "A text value",
"number__c": "42.0",
"another_number__c": null,
"date_field__c": "2042-01-01",
"picklist__c": "Option A",
"file_attachment__Name__s": "filename.txt",
"file_attachment__Length__s": "206.0",
"file_attachment__Body__s": "/services/data/v45.0/sobjects/Offer__kav/ka02p000000kqHKAAY/file_attachment__Body__s",
"file_attachment__ContentType__s": "text/plain",
}Binary content can be retrieved only from Articles.
Translations
Articles in Salesforce can be translated into different languages.
This connector exposes the existing language mutations of Articles in languages which are added in the Knowledge Base of the connected Salesforce instance.
Language mutations can be obtained using the scope translations_all_*.
Please note that results of such calls may include duplicate entries for one language, as both draft and online version of the Article may exist in that language.
When creating an Article without the use of translationOf field in the language decorator a master language Article is created.
If the tag field is not filled either, the Article is created in the default language of the connected Salesforce instance.
Only languages which are marked active in the connected Salesforce Knowledge base are valid tag values.
In Salesforce Categories assigned to an Article are tied to its master language mutation. This has several implications:
-
Translations of Articles are always created with the same set of assigned Categories as the master language Article.
-
Updating parents of master language Article will also change the parents of its translations.
-
Updating parents of Article translations is not a valid operation and will result in Operation Not Allowed.
Deleting a master language Article will result in all of its translations being deleted as well.
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
|
|
|
|||
|
|
3.16.3. Mappings
| Decorator | Used By | Field in Salesforce | Writable | Description |
|---|---|---|---|---|
|
|
Whether the entity can have |
||
|
|
|
The type of the Article with its suffix as used by Salesforce backend. Not always present, please see note bellow. |
|
|
|
|
The type of the Article in human readable form, i.e. without |
|
|
|
|
Date and time when the Article was created. |
|
|
|
|
The id of the user that created the Article. |
|
|
|
|
The name of the user that created the Article. |
|
|
|
|
The email of the user that created the Article. |
|
|
|
|
The summary of the Article. |
|
|
|
|
Only during create operation. |
The language of the Article. Only languages active in connected Knowledge base. |
|
|
Only during create operation. |
The id of the master translation of this Article. |
|
|
|
|
Date and time of the last modification of the Article. |
|
|
|
|
The id of the user that last modified the Article. |
|
|
|
|
The name of the user that last modified the Article. |
|
|
|
|
The email of the user that last modified the Article. |
|
|
|
ArticleType |
The entity name as used by Salesforce backend. |
|
|
|
|||
|
|
|||
|
|
ArticleType without suffix |
A human readable version of the entity name as displayed by Salesforce. |
|
|
|
|||
|
|
|||
|
|
|
The version number of the Article. |
|
|
|
The XDIP of the repository root. |
||
|
The XDIP of the |
|||
|
The XDIP of the parent Category Group or Category. |
|||
|
The XDIP of one of the parent entities of the |
The contentType decorator is not filled for Articles which are displayed as a result of requesting the scope path_children_entity of any Category. Otherwise the request would be much more resource expensive operation due to limitations of Salesforce API.
|
3.16.4. RPC Endpoints
As there is no entity status support in Xillio API yet, this connector supports retrieving and changing the publish status of Articles with the use of RPC.
The supported publish statuses are (case insensitive): draft, online, archived.
Changing status from draft to archived or from archived to online is not supported and will result in OperationNotAllowed error.
Article translations can only change status from online to draft, other changes happen automatically, when the master of the translation changes status.
Furthermore draft Article translations can be marked as "sent for publication" which determines, whether they are automatically published when their master is published.
| Once an Article is archived its translations cannot be restored. |
article
article/publishStatus
Used to get or set the publish status of the specified Article.
POST /v2/rpc/{configurationId}/article/publishStatus
------
HTTP/1.1 200 OK
Content-Type: application/json
Input |
Type |
Default |
Description |
|
|
The XDIP of the Article for which the operation is to be executed. |
|
|
|
|
The desired publish status to be set; leave out or put empty string to get the status. |
Returns PublishStatusResult: the result of the operation.
Path |
Type |
Description |
|
|
The current XDIP of the Article. |
|
|
The current publish status of the Article. |
{
"publishStatus" : "online",
"xdip" : "xdip://configuration-id/Article/ka02p000000lKN1AAN"
}article/translationSentForPublication
Used to get or set whether the specified draft Article translation is sent for publication.
If true, the draft translation is automatically published when its master is published.
POST /v2/rpc/{configurationId}/article/translationSentForPublication
------
HTTP/1.1 200 OK
Content-Type: application/json
Input |
Type |
Default |
Description |
|
|
The XDIP of the draft Article translation for which the operation is to be executed. |
|
|
|
|
Whether to set the state; leave out or set false to get the state. |
|
|
|
Whether to send the translation for publication; only relevant when |
Returns TranslationSentForPublicationResult: the result of the operation.
Path |
Type |
Description |
|
|
The current XDIP of the Article translation. |
|
|
The current publish status of the Article translation. |
|
|
Whether the Article translation is sent for publication. |
{
"sentForPublication" : true,
"publishStatus" : "draft",
"xdip" : "xdip://configuration-id/Article/ka02p000000lLPNAA2"
}3.16.5. RPC Models
PublishStatusResult
Result of getting or setting the publish status of an Article.
Field |
Type |
Description |
|
|
The current XDIP of the Article. |
|
|
The current publish status of the Article. |
TranslationSentForPublicationResult
Result of sentForPublication call.
Field |
Type |
Description |
|
|
The current XDIP of the Article translation. |
|
|
The current publish status of the Article translation. |
|
|
Whether the Article translation is sent for publication. |
3.17. SharePoint
SharePoint is a web-based collaborative platform.
Version(s): we support the latest version of SharePoint Online and we also support on-premise installations of SharePoint 2013 and 2016.
3.17.1. Configuration
The SharePoint connector configuration consists of the following values:
| Parameter | Description |
|---|---|
The base URL of the SharePoint instance. |
|
The URL of the Microsoft authentication endpoint. |
|
The username of an account on SharePoint. |
|
The password of the account. |
|
Windows NT Domain name, for SharePoint On-Premises only. |
|
Site URL part which usually takes one of 2 forms: "sites/MySite" or just "MySite" |
|
The version of SharePoint instance. Supported values: 2013, 2016. Default value is 2016. Default: |
| The "site" and "baseUrl" can be determined when you enter the site home page using the SharePoint user interface. Url in the web browser should be in form of {baseUrl}/{site}/SitePages/Home.aspx For example: https://some.sharepoint.com/MySite/SitePages/Home.aspx |
| The "domain" property of the configuration should be left empty if you need to connect to SharePoint Online. |
{
"configurationType": "SharePoint",
"config" : {
"baseUrl" : "https://your-company.sharepoint.com",
"username" : "username",
"password" : "password",
"site" : "MySite"
}
}3.17.2. Features and Limitations
Content Types
The SharePoint connector supports two types of the content: files and folders.
Currently, the connector is only capable of creating files with the default SharePoint Content Type.
The SharePoint connector does not support resolving the content type of previous versions of an entity.
Currently, this connector has limited support for the content types and metadata for configurations using SharePoint 2013.
File Versioning
The SharePoint connector supports "versions" and "versionList" scopes and through that allows you to retrieve metadata and content of the previous versions of the files as well. Uploading the new content of a file creates a new version but updating file’s metadata keeps the version.
However your SharePoint site needs to be configured to support file versioning. Otherwise the version of all files will be constant and updating a file’s content won’t create a new version.
Moving Folders
Due to the limitations in the SharePoint REST API the SharePoint connector does not support moving folders.
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|
||
|
3.17.3. Mappings
These are the decorators that are set for certain kinds of entities in SharePoint.
Entities retrieved via SharePoint connector can be of kind SharePointFile or SharePointFolder.
There are differences between values provided by SharePoint Online and on-premise
versions of SharePoint and the connector always returns all the values that are
available at the moment.
The content type decorator is ignored for write-operations and creation of entities with kind SharePointFile will result in
creating a file with SharePoint’s default content type.
| Decorator | Used By | Read-only | Field in SharePoint | Description |
|---|---|---|---|---|
|
|
True |
This decorator is only set for folders, and value |
|
|
All entities |
True |
|
The human readable name of the content type associated with the requested SharePoint entity. |
|
All entities |
True |
Computed from |
The id of the list in which this content type resides followed by the id of the content type associated with the requested SharePoint entity. |
|
All entities |
True |
|
Date and time when the requested entity was created. |
|
All entities |
True |
|
Details of the user that created the requested entity. |
|
All entities |
False |
|
Description associated with the requested SharePoint entity. |
|
|
True (update Name decorator to change extension) |
Computed from |
The extension of the requested file, or an empty string if it has none. |
|
|
True (update Name decorator to change extension) |
Computed from |
The sanitized extension of the requested file. |
|
|
True |
|
The size in bytes of the requested file. |
|
All entities |
True |
Computed from |
The path to the requested entity relative to the SharePoint site’s root. |
|
All entities |
True |
|
Last modified date and time of the requested entity. |
|
All entities |
True |
|
Details of the last user that modified the requested entity. |
|
All entities |
True |
|
The name of the requested entity. |
|
All entities |
False (update this decorator to rename entity or change file’s extension) |
|
The name of the requested entity. |
|
All entities |
False (update this decorator to move entity to new location) |
Computed from |
The XDIP of the parent entity. |
|
|
True |
|
Current version of the file. |
3.18. SharePointV2
SharePoint is a web-based collaborative platform.
Version(s): we support the latest version of SharePoint Online only. This connector will not work with on-premise installation.
3.18.1. Configuration
The SharePoint connector configuration consists of the following values:
| Parameter | Description |
|---|---|
The base URL of the SharePoint instance. |
|
The URL of the Microsoft authentication endpoint. |
|
The SharePoint app client-id to access the API. |
|
The SharePoint app client secret to access the API. |
|
ID of the SharePoint tenant. |
|
Site URL part which usually takes one of 2 forms: "sites/MySite" or just "MySite" |
|
The version of SharePoint instance. Supported values: 2013, 2016. Default value is 2016. Default: |
|
Resource information identifying Microsoft application. Default: |
| The "site" and "baseUrl" can be determined when you enter the site home page using the SharePoint user interface. Url in the web browser should be in form of {baseUrl}/{site}/SitePages/Home.aspx. For example: https://some.sharepoint.com/MySite/SitePages/Home.aspx |
Registering SharePoint Add-In (getting clientId and clientSecret)
-
In browser, enter https://<tenant>.sharepoint.com/_layouts/15/appregnew.aspx, there will appear a 5 field form
-
For lines
Client IdandClient Secret, click theGeneratebutton and store the output in your credential storage -
Name the configuration in the
Titlefield -
For
App DomainandRedirect URIenter some dummy values likelocalhostandhttps://localhostrespectively, because we don’t use them -
Press the
Createbutton
| Each field of the form is mandatory |
In this example and the example below, the process of registration and granting permissions is shown for all sites at once. If you want to register Add-In for a specific site, add its name between .com/ and /_layouts, e.g. https://<tenant>.sharepoint.com/<site>/_layouts/15/appregnew.aspx. Example for granting permissions will be presented below.
|
Granting the permission to Add-In
-
In browser, enter https://<tenant>.sharepoint.com/_layouts/15/appinv.aspx, there will appear a form with 4 field and 1 text box.
-
In the
App Idfield, enter your previously generatedClient Idand pressLookup -
In the
Permission Request XMLtext box enter the below XML<AppPermissionRequests AllowAppOnlyPolicy="true"> <AppPermissionRequest Scope="<value>" Right="<value>" /> </AppPermissionRequests>
Possible values will be described in a note below
-
Press
Create -
You will be redirected to a page where you are asked if you trust the
Add Into manage the site -
Press
Trust it
As was mentioned in the previous note, you can grant permission to a specific site only by adding its name between .com/ and /_layouts, e.g. https://<tenant>.sharepoint.com/<site>/_layouts/15/appinv.aspx.
|
| There are several possible scopes and rights. For most cases, we recommend using the Scope of "http://sharepoint/content/sitecollection" and Right of "Write". In case of any specific requirements, you can refer to the official Microsoft documentation regarding the scopes and rights. |
Getting Tenant Id
-
Go to https://<tenant>.sharepoint.com/<site>/_layouts/15/appprincipals.aspx
-
In the
App Display Namecolumn, find the required application -
In the opposite column of
App Identifieryou will se a string likei:0i.t|ms.sp.ext|ClientId@TenantIdwhere you can copy the value
Getting Resource Id
If you use SharePoint on-premises, please, contact your administrator to receive your Resource Id.
In case of SharePoint online, use the default value.
{
"configurationType": "SharePointV2",
"config" : {
"baseUrl" : "https://your-company.sharepoint.com",
"clientId" : "91391ad5-f8b4-4007-8e98-e2e695c0bcb2",
"clientSecret" : "mQ1eApeD251QJkNBodWRGYCES2PnEhaq1+YoM0DHrw8=",
"tenantId" : "f15805d7-484f-456f-b28d-5f3afae0f44b",
"site" : "MySite"
}
}3.18.2. Features and Limitations
Content Types
The SharePoint connector supports two types of the content: files and folders.
Currently, the connector is only capable of creating files with the default SharePoint Content Type.
The SharePoint connector does not support resolving the content type of previous versions of an entity.
Currently, this connector has limited support for the content types and metadata for configurations using SharePoint 2013.
File Versioning
The SharePoint connector supports "versions" and "versionList" scopes and through that allows you to retrieve metadata and content of the previous versions of the files as well. Uploading the new content of a file creates a new version but updating file’s metadata keeps the version.
However, your SharePoint site needs to be configured to support file versioning. Otherwise, the version of all files will be constant and updating a file’s content won’t create a new version.
Moving Folders
Due to the limitations in the SharePoint REST API the SharePoint connector does not support moving folders.
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|
||
|
3.18.3. Mappings
These are the decorators that are set for certain kinds of entities in SharePoint.
Entities retrieved via SharePoint connector can be of kind SharePointFile or SharePointFolder.
There are differences between values provided by SharePoint Online and on-premise
versions of SharePoint and the connector always returns all the values that are
available at the moment.
The content type decorator is ignored for write-operations and creation of entities with kind SharePointFile will result in
creating a file with SharePoint’s default content type.
| Decorator | Used By | Read-only | Field in SharePoint | Description |
|---|---|---|---|---|
|
|
True |
This decorator is only set for folders, and value |
|
|
All entities |
True |
|
The human readable name of the content type associated with the requested SharePoint entity. |
|
All entities |
True |
Computed from |
The id of the list in which this content type resides followed by the id of the content type associated with the requested SharePoint entity. |
|
All entities |
True |
|
Date and time when the requested entity was created. |
|
All entities |
True |
|
Details of the user that created the requested entity. |
|
All entities |
False |
|
Description associated with the requested SharePoint entity. |
|
|
True (update Name decorator to change extension) |
Computed from |
The extension of the requested file, or an empty string if it has none. |
|
|
True (update Name decorator to change extension) |
Computed from |
The sanitized extension of the requested file. |
|
|
True |
|
The size in bytes of the requested file. |
|
All entities |
True |
Computed from |
The path to the requested entity relative to the SharePoint site’s root. |
|
All entities |
True |
|
Last modified date and time of the requested entity. |
|
All entities |
True |
|
Details of the last user that modified the requested entity. |
|
All entities |
True |
|
The name of the requested entity. |
|
All entities |
False (update this decorator to rename entity or change file’s extension) |
|
The name of the requested entity. |
|
All entities |
False (update this decorator to move entity to new location) |
Computed from |
The XDIP of the parent entity. |
|
|
True |
|
Current version of the file. |
3.19. Sitecore
Sitecore is a CMS with additional marketing functionality that analyses customer data from multiple sources and makes it possible to show custom content.
Version(s): we support version 9 of Sitecore.
3.19.1. Configuration
The configuration for the Sitecore connector consists of the following values:
| Parameter | Description | ||
|---|---|---|---|
The base URL of the Sitecore instance. |
|||
The username of an account on Sitecore. |
|||
The password of the account. |
|||
Database on the Sitecore target system. Valid values are |
|||
The domain to which to connect. |
|||
Enable this setting to ignore the expiry date on cookies.
Default: |
{
"configurationType": "Sitecore",
"config" : {
"baseUrl" : "https://sitecore.mydomain.com",
"username" : "username",
"password" : "password",
"database" : "master",
"domain" : "sitecore"
}
}Settings
To use the Sitecore connector you will need to change some settings.
-
You need to set
Media.RequestProtection.Enabledin the fileSitecore.Media.RequestProtection.configtoFalse. -
You need to set
Sitecore.Services.SecurityPolicyin the fileSitecore.Services.Client.configto"Sitecore.Services.Infrastructure.Web.Http.Security.ServicesOnPolicy, Sitecore.Services.Infrastructure". -
You need to add the following line to the
servicesblock in the fileSitecore.Services.Client.config:
<configurator type= "XillioSitecorePlugin.ItemService.XillioItemServiceConfigurator, XillioSitecorePlugin" />. -
You need to replace the line:
<add verb="*" path="sitecore_media.ashx" type="Sitecore.Resources.Media.MediaRequestHandler, Sitecore.Kernel" name="Sitecore.MediaRequestHandler"/>
with the line:
<add verb="*" path="sitecore_media.ashx" type="XillioSitecorePlugin.ItemService.XillioMediaRequestHandler, XillioSitecorePlugin" name="Sitecore.MediaRequestHandler"/>
in the fileWeb.config.
Plugin
To use the Sitecore connector you will need to install the Xillio Sitecore Plugin into the Sitecore instance.
This is done by adding the .dll file to the bin folder in your Sitecore site. This folder is located at:
wwwroot\<your-site-name>\bin.
3.19.2. Features and Limitations
DisplayName is only updatable on the base language.
Furthermore changing the DisplayName alone is not seen as a change by Sitecore and thus is not handled.
Languages
An entity can be translated to multiple languages. To do this you will have to call Create a New Entity or Create a New Entity With Contents on an already existing entity. This means that an entity in the Sitecore base language must already be present at the location that you are pointing to in your request. To add a translation simply set the language decorator to the language of the translation you want to create.
It is not allowed to create a new item in a different langauge than the base Sitecore language.
Plugin
When you don’t want to or are not able to use the above mentioned plugin some functionality of the Sitecore connector will be lost.
The following functions will cease to work:
-
Translation scope.
-
Version scope.
-
Create file in Media Library.
-
Update contents of file in Media Library.
Media Limitations
-
Items inside the
Media Libraryare seen as aMediaItem. These items behave differently from normal items. -
A
MediaItemcan only be created in theMedia Library. -
When creating a
MediaItemusing Create a New Entity With Contents thecontentsis the binary contents of the file that will be created. For other items (anything created outside of theMedia Library) thecontentsis JSON containing raw data to be put into Sitecore. The same goes for the content of Update an Entity's Contents and Download an Entity's Contents. -
Because of how Sitecore is designed it is not possible to have multiple versions of a media item that contain different content. It is possible to have multiple versions or language of a media item. These versions and languages can also have different metadata. But the contents of the media item will always be te content that was last uploaded to the item. Because of this the version of the media item is not incremented when Update an Entity's Contents is called.
Character Limitations
By default Sitecore has very strict rules on how its items can be named. The default settings for this are:
<setting name="InvalidItemNameChars" value="\/:?"<>|[]" /> and
<setting name="ItemNameValidation" value="^[\w\*\$][\w\s\-\$]*(\(\d{1,}\)){0,1}$" />
These settings can be found in the Sitecore.config file.
The ItemNameValidation setting is most restrictive as it dictates the regex that a new name will have to comply with.
If a wider range of symbols is needed, you can change the settings. There are some character that are not supported by Sitecore even if they are allowed in the settings. These characters are:
< > | / \ "
When using one of the characters that is not allowed a Operation Not Allowed error will be thrown.
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|
||
|
|
3.19.3. Mappings
| Decorator | Used By | Field in Sitecore | Description |
|---|---|---|---|
|
All entities |
Whether the item has children. |
|
|
All entities |
|
The template that the item uses. |
|
All entities |
|
The template that the item uses. |
|
All entities |
|
The time and date that the item was created. |
|
All entities |
|
The user that created the item. |
|
All entities |
|
The description of the item. |
|
All entities |
|
The extension of the media item. |
|
All entities |
Computed from the raw extension. |
|
|
All entities |
|
The size of the file in bytes. |
fileSystem.path |
|||
|
|||
|
|||
|
|||
|
All entities |
|
The ISO 639-1 language of the item. |
|
All entities |
|
The mime type of the requested file, based on the extension. If the extension is unknown, this is set to |
|
All entities |
|
The time and date the item was last modified. |
|
All entities |
|
The user who last modified the item. |
|
All entities |
|
The name of the item as used by Sitecore. |
|
All entities |
|
The name of the item as displayed by Sitecore. |
|
All entities |
Computed from the path of the item. |
|
|
|||
|
All entities |
|
The version number of the item. |
3.20. TRIM (HPE Content Manager)
This is the connector for the HPE Content Manager, which was previously named HPE Records Manager and HP TRIM. This system will be referred to as TRIM in the remainder of the documentation. TRIM is an electronic document and records management system.
Version(s): we support version 9.10 of TRIM.
3.20.1. Configuration
The configuration for this connector consists of the following values:
| Parameter | Description |
|---|---|
The absolute URL to the TRIM Service API. |
|
The username of an account on TRIM. |
|
The password of the account. |
|
A TRIM query string, see Root Query. Default: |
| The connector currently only supports HTTP basic authentication, this can be configured on the IIS instance serving the TRIM Service API. |
{
"configurationType": "Trim",
"config" : {
"baseUrl" : "http://trim.xillio.com/HPECMServiceAPI/",
"username" : "username",
"password" : "password"
}
}Root Query
The rootQuery configuration parameter defines the set of children of the root entity. It is formatted as a TRIM query
string which is passed to TRIM and determines what records to fetch. The following are common examples of queries:
| Parameter name | Description |
|---|---|
|
All documents |
|
Documents in container 1234 |
|
Documents not in any container |
The root query string will be passed to the q parameter of the TRIM Record endpoint. Refer to the TRIM documentation
for more details on building queries.
|
| The root query results will be fetched from TRIM using pagination. This uses the default page size configured in TRIM. |
3.20.2. Features and Limitations
When using the TRIM connector, keep in mind the following:
-
TRIM record metadata can be retrieved using the
/entitiesendpoint. -
Electronic documents attached to TRIM records can be retrieved using the
/contentsendpoint. -
The connector is read-only: only
GETis supported on the endpoints mentioned above. -
The children of the root entity can be specified using the Root Query.
-
TRIM record renditions are not currently supported.
-
HTTP basic is currently the only supported authentication method.
-
Versioning in the TRIM Connector is based on the revisions of the HP Trim system. These revisions are incremental but not necessarily starting from 0, and with the same step size. This should be noted when working with versions.
-
Retrieving the revisions of content is currently not supported.
-
This connector fully supports Named Queries.
Requesting Records and Their Documents
The TRIM connector can be used to retrieve TRIM Records and electronic documents attached to these records. The
/entities endpoint will retrieve record metadata from TRIM, while the /contents endpoint can be used to retrieve
records' electronic documents.
The URLs for the /entities and /contents endpoints follow a rigid structure when using the TRIM connector:
https://demo-tenant.xill.io/v2/entities/{configuration}/{type}/{id}
| Field | Type | Description |
|---|---|---|
|
|
The configuration id of the TRIM connector configuration. |
|
|
Currently, only the |
|
|
The id of the requested entity, corresponds to the id in TRIM. |
The connector is read-only: only GET on the /entities and /contents endpoints is supported.
|
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|
||
|
3.20.3. Mappings
These are the decorators that are set for TRIM. These only map to entities of kind Record, since that is the only entity
kind currently supported.
| Decorator field | Used By | Field in TRIM | Description |
|---|---|---|---|
|
|
||
|
|
|
Internal type name |
|
|
|
Internal type name. |
|
|
|
Creation timestamp. |
|
|
|
Creator’s display name. |
|
|
|
Creator’s internal id. |
|
|
|
Creator’s email. |
|
|
|
Description of the record’s state. |
|
|
|
Associated document file name extension, as is. |
|
|
|
Associated document file name extension, normalized. |
|
|
|
Associated document size in bytes. |
|
|||
|
|||
|
|||
|
|
|
Associated document mime type. |
|
|
|
Last modification timestamp. |
|
|
|
Last updater’s display name. |
|
|
|
Last updater’s internal id. |
|
|
|
Last updater’s email, |
|
|
|
Internal id. |
|
|
|
Title. |
|
|||
|
|||
|
|
|
Version’s id. |
3.21. WordPress
WordPress is a free and open-source content management system (CMS). Features include a plugin architecture and a template system.
Version(s): we support WordPress version 4.7 or higher.
3.21.1. Configuration
Authentication plugins
Xillio API WordPress connector requires either JWT Authentication for WPI-API plugin or Application Passwords plugin to be installed in target WordPress instance.
| Having both of these plugins installed and active at the same time can lead to unexpected behavior. |
"Application passwords" plugin
You can find the plugin here. This plugin is easy to install and provides users a new login password just for WP REST API. This new password cannot be used to login into WP Administration area.
After installing the plugin, navigate to Users - Your Profile - Application Passwords, here you can create your new WP REST API password.
To make Xillio API WordPress connector use this type of authentication, set authenticationType in configuration to basic.
"JWT Authentication for WP-API" plugin
You can find an installation guide here. This plugin extends the WP REST API with JSON Web Tokens Authentication as an authentication method.
After installing the plugin, make absolutely sure you override the default JWT secret. The CONFIGURATION section of the installation guide walks you through the process.
To make Xillio API WordPress connector use this type of authentication, set authenticationType in configuration to jwt
WordPress connector configuration
The WordPress connector configuration consists of the following values:
| Parameter | Description |
|---|---|
The URL of the WordPress site. |
|
The username of an account on WordPress (with Administrator privileges). |
|
The password of the account, or the generated application password, depending on the authentication type. |
|
A WordPress OAuth2 token. Optional if logging in with a |
|
Specifies which authentication type the connector should use. Valid options are Default: |
These values allow the WordPress connector to connect and authorize with the target WordPress site.
The Administrator role is needed for the connector to be able to retrieve author information and more detailed metadata.
{
"configurationType": "WordPress",
"config" : {
"baseUrl" : "https://demo.wp-api.org/",
"username" : "username",
"password" : "password"
}
}3.21.2. Features and Limitations
Entity types and hierarchy
The connector reveals all types of WordPress entities that are defined visible for the WordPress REST API.
The children of root are virtual collections grouping the entities of each of these types. The collections are strictly read-only. All entities of certain type can be retrieved by requesting the children of the respective collection.
On top of that WordPress pages can be organized in a tree structure defining parent page of a page. WordPress connector allows you to set and modify the parent page. To "unset" parent page set the parent of page to Pages collection.
When you delete a page that is set as parent of other pages then these pages will only lose their parent relation. They and their content still remain part of WordPress site and you can list them as children of Pages collection.
-
/Pages
-
Page: Home
-
Page: About Us
-
Page: The Team (A sub-page of 'About Us')
-
-
Page: Contact
-
-
/Media
-
logo.png
-
welcome.jpg
-
-
/Posts
-
Post: Welcome to WordPress
-
Post: How to Connector to WordPress Using Xillio API
-
General limitations
All entities are created as "Draft" unless indicated otherwise using the workflow decorator. Currently, the WordPress connector does not support custom statuses. Furthermore, changing the visibility of a page or post, such as from public (which is shown as publish) to private, is only possible for the master post, not its translation. Changing to draft is possible for any page or post.
When creating or updating an entity, the value name.systemName is always converted internally by WordPress. The conversions consist of lowering upper case letters, replacing dots with dash, etc.
When an entity is deleted from WordPress, it is deleted permanently.
Media limitations
WordPress does not allow to create media entities without content and versioned media entities. In addition, media item’s binary content cannot be updated.
When creating a media entity the value name.systemName is used as a WordPress filename and must conform to internal WordPress rules. WordPress will refuse your request if an invalid filename is used.
Permalinks settings
A permalink is the web address used to link to your WordPress content. WordPress allows you to choose your permalink structure. Here you can learn what Permalinks settings are and how to change it.
| If your WordPress server uses the 'Plain' setting for permalinks by default and our connector is not able to reach the API with these settings. Make sure to resolve this, either by picking another permalink setting (e.g. Numeric) or by adding server rewrite rule similar to the one in the example below. |
Nginx rewrite rule example to bypass WordPress 'Plain' permalinks settings limitation:
location ~ ^/wp-json/ {
rewrite ^/wp-json/(.*?)$ /?rest_route=/$1 last;
}Translation scope support
Our WordPress connector can support translation scope if
-
target WordPress instance uses WPML plugin
-
target WordPress instance uses Xillio WPML REST API plugin
WPML is the WordPress Multilingual Plugin allowing to build and run multilingual sites. But WPML plugin does not extend WordPress Rest API to allow to retrieve multilingual details, so Xillio made a plugin to extend the WordPress API. Therefore you need one additional plugin. You can download Xillio WPML REST API Plugin version 1.3 from Cloudsmith.io.
It is a zip file that you can use to install the plugin manually. To install the plugin go to the Plugins section of the WP Admin, click "Add new", click "Upload Plugin", select the downloaded zip file and click "Install now". WordPress decompresses the file and installs the plugin automatically.
Note that the WPML plugin allows for creating custom language definitions. The value of the field code of language definition in WPML settings is what is used to fill the language decorator of entities and as such is required to be BCP-47 compliant. Existing entities with non-compliant language codes will be exposed having no language decorator, empty translation list and will not appear in translation list of other entities.
Creating new translations
Translations are supported for all types of entities.
When creating an entity you can also specify its language. To do so, just fill the value of language.tag with the WordPress code of the language. For example
{
"kind" : "Page",
"original" : {
"name" : {
"systemName" : "a-new-wordpress-page",
"displayName" : "A new WordPress page"
},
"language": {
"tag": "en"
}
}
}If you don’t specify the value of language.tag, the entity will be created using the default language of the WordPress site.
To create a new translation of an existing entity, fill the value of language.translationOf with id of its desired master entity. For example
{
"kind" : "Page",
"original" : {
"name" : {
"systemName" : "neue-deutsch-seite",
"displayName" : "Neue Deutsch Seite"
},
"language": {
"tag": "de",
"translationOf": "https://demo-tenant.xill.io/v2/entities/wordpress/pages/12345"
}
}
}As values of language.tag always use language’s code as defined in your WordPress instance. You can find those codes in WordPress Admin in WPML section.
If WPML’s 'When uploading media to the Media library, make it available in all languages' option is checked, creation of new media will result in creation of media for each language that is configured in WPML plugin.
This is default WPML behaviour and it can be changed in WPML plugin settings.
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|
||
|
|
3.21.3. Mappings
These are the decorators that are set for certain types in WordPress.
Entities retrieved via WordPress can be of kind Page, Post or Media.
| Decorator | Used By | Writeable | Field in WordPress | Description |
|---|---|---|---|---|
|
|
False |
type |
Type of the entity |
|
|
False |
type |
Type of the entity |
|
|
False |
n/a |
This decorator is set for Pages only, and value |
|
|
True |
|
Date and time when the requested entity was published. |
|
|
False |
|
Login name for the user that published the requested entity. |
|
|
False |
|
Name of the user that published the requested entity. |
|
|
False |
|
Email of the user that published the requested entity. |
|
|
True |
|
Media entity description. |
|
|
False |
|
The path to the requested media relative to the WordPress media root. |
|
|
True |
|
The language tag of the requested entity |
|
|
Can be specified when creating an entity to create a translation relation between entities. However, it is ignored during entity updates. |
|
The id of the entity from which the requested entity was translated |
|
|
False |
|
The mime type of the requested Media resource. |
|
|
False |
|
Last modified date and time of the requested entity. |
|
|
True |
|
Title of the requested entity. |
|
|
True |
|
Alphanumeric identifier for the entity unique to its type. |
|
|
False for |
Computed from XDIP or |
The XDIP of the parent entity. |
|
|
False |
|
URL that can display the requested entity in the browser. |
|
|
False |
|
The version number of the Page or Post. |
|
|
True |
|
The publication status of an entity. |
3.22. Zendesk
Zendesk Guide is a knowledge base for smart self-service. It helps companies increase customer and agent satisfaction, while also reducing support costs.
Version(s): we support the online version of Zendesk.
3.22.1. Configuration
Zendesk connector configuration
The Zendesk connector configuration consists of the URL of your Zendesk site, authentication credentials and optional permission information.
| Parameter | Description |
|---|---|
The URL of the target Zendesk site. |
|
Depending on your authentication method, either of:
|
|
Depending on your authentication method, either of:
|
|
A Zendesk OAuth2 token. Should not be provided if |
|
Optional. |
Management Permission Groups
A management permission group defines which agents can create, update, archive, and publish articles.
The articles created with Xillio API will have the permission group set to the one specified in the configuration.
The field permissionGroupId is optional.
When left empty, the id of the built-in group Managers is used.
| The credentials used in the configuration must belong either to an administrator or to a user who is a member of the used permission group. Otherwise, requests for creating articles will result in unexpected behavior. |
For how to obtain a permission group id and more information, please see Zendesk documentation.
Authentication in Zendesk
Authenticating to Zendesk can be done in three different ways:
-
With a username and a password
-
With a username and an API token
-
With an OAuth access token
All three ways can be enabled or disabled in the Zendesk Support admin interface at . Check or ask in advance what ways of authentication are actually allowed in your Zendesk instance.
Configuration with username and password
| Please note that this way of authenticating to Zendesk API works only if the user account does not have two-factor authentication enabled. |
| Parameter | Description |
|---|---|
|
The URL of the target Zendesk site. |
|
The email you use to login to the Zendesk web interface. |
|
The password you use to login to the Zendesk web interface. |
|
Optional. The id of the management permission group that is used when creating articles. |
{
"configurationType": "Zendesk",
"config": {
"baseUrl": "https://yoursite.zendesk.com",
"username": "your@email.com",
"password": "password",
"permissionGroupId": 2102353
}
}Configuration with API token
API tokens are different from OAuth tokens, which are detailed in the next section. API tokens are auto-generated passwords in the Support admin web interface.
As passwords, API tokens can be used to impersonate anyone in the account, including admins. Make sure to keep them secure, and delete any unused tokens.
API tokens are managed in the Support admin interface at . The page lets you view, add, or delete tokens. More than one token can be active at the same time. Deleting a token deactivates it permanently.
| Parameter | Description |
|---|---|
|
The URL of the target Zendesk site. |
|
The email you use to login to the Zendesk web interface appended with the string |
|
A valid API token. |
|
Optional. The id of the management permission group that is used when creating articles. |
{
"configurationType": "Zendesk",
"config": {
"baseUrl": "https://yoursite.zendesk.com",
"username": "your@email.com/token",
"password": "svK9aw4O8wFqIj7qpTpml0Sgh9QXc1oK2q857IjN",
"permissionGroupId": 2102353
}
}Configuration with OAuth token
OAuth provides a secure way for your application to access Zendesk data without having to store and use the passwords of Zendesk users, which is sensitive information.
You must register your application to generate OAuth credentials that your application can use to authenticate API calls to Zendesk.
You can find in depth description how to set up OAuth with Zendesk in this article.
| Parameter | Description |
|---|---|
|
The URL of the target Zendesk site. |
|
A Zendesk OAuth2 token. |
|
Optional. The id of the management permission group that is used when creating articles. |
{
"configurationType": "Zendesk",
"config": {
"baseUrl": "https://yoursite.zendesk.com",
"token": "fdb8fdbecf1d03ce5e6125c067733c0d51de209c",
"permissionGroupId": 2102353
}
}3.22.2. Features and Limitations
This connector has read, write and translation functionality. There is no custom metadata and search support.
User privileges
The Admin or Agent user privileges are required for many operations of this connector.
Using credentials with lesser privileges might result in errors or not being able to access all the available content.
If you don’t provide the permissionGroupId in the configuration then the connector will set the permission group of the new articles to the "Managers" group.
This will only succeed if you provide credentials of the user that is classified as Manager.
Entity types and hierarchy
The connector exposes three types of Zendesk entities: Categories, Sections, and Articles.
Zendesk entities are organized in a tree structure. Top level entities are Categories. Categories contain Sections and only Sections can contain Articles. The children entities (Articles and Sections) have always just one parent entity.
Binary content can be retrieved only from Articles.
Our connector also exposes three virtual collections called categories, sections and articles, grouping entities of the respective type.
These collections are strictly read-only and can be reached by explicit request.
All source language entities of one type can be retrieved by requesting the children of the respective collection.
For example, You can get information about all articles in their source language(s) with the following request:
GET /v2/entities/{configurationId}/articles?scope=path_children_entityTranslations
Zendesk employs the concept of source translation. An entity can be created in any language enabled in the Zendesk Guide administration UI. Once created, its language becomes the source language of this entity and all of its translations.
When an entity is deleted, all of its translations are deleted as well.
Translations cannot be moved on their own. Instead, all translations of an entity are moved together when the source entity itself is moved.
The source translation of an entity cannot be deleted, an attempt to do so will result in an Operation Not Allowed error.
| Operation | Supported | Remark | |
|---|---|---|---|
Get translation entity |
Use the id obtained from a |
||
Create new entity with language specified |
Entity can exist in non-default language. The specified language becomes the source language for this entity. |
||
Create new translation of existing entity |
Use the field |
||
Delete translation entity |
Non-source translations only. |
||
Update translation entity |
Name |
||
Description |
|||
Parent |
Not supported in Zendesk. |
||
Language |
|||
Update entity language |
Not supported in Zendesk. |
||
Get binary content of translation |
Articles only. |
||
Update binary content of translation |
Articles only. |
||
Scopes
-
entity -
metadata
parents |
children |
all |
|
|---|---|---|---|
|
|
||
|
|||
|
|
3.22.3. Mappings
These are the decorators that are set for certain types in Zendesk.
Entities retrieved from Zendesk can be of kind Category, Section or Article.
| Decorator | Used By | Writable | Field in Zendesk | Description |
|---|---|---|---|---|
|
|
False |
n/a |
Type of the entity. |
|
|
False |
n/a |
This decorator is set for Categories and Sections only, and value |
|
|
False |
|
Date and time when the requested entity was created. |
|
|
False |
|
The name for the user that published the requested entity. |
|
|
True |
|
The entity description. |
|
|
True |
|
The language of requested entity. |
|
|
False |
|
Last modified date and time of the requested entity. |
|
|
True |
|
The entity name |
|
|
True |
|
The XDIP of the parent entity. |
|
|
True |
|
The XDIP of the parent entity. |
|
|
False |
|
URL that can display the requested entity in the browser. |
|
|
True |
|
The publication status of an article within Zendesk. |