Welcome

The Connecting-Expertise Vendor Management System, further referred to as CE-VMS, exposes services via REST. With our REST API, called Connecting-Expertise OpenApi, further referred to as CE-OpenApi, you develop applications that are able to exchange (read and write) data with the CE-VMS.

Our Connecting-Expertise OpenApi Event Message Inbox, further referred to as CE-OpenApi EMI, is a queue system. When you subscribe to this queue system, each CE-VMS application event is published to your message inbox as a unique message. You’ll be notified when a new message has been published, and will be able to respond accordingly.

The documentation is divided in three major sections:

Getting started

This section tells you everything you need to know about the creation of a request for our CE-OpenApi via a REST-client, and how to use the CE-OpenApi EMI.
It gives an overview of how requests are structured and what you can expect as a response. If you’ve used a REST-API before then you’ll know most of this already.

Essentials

This section contains generic information, how to?,…​ . Background information that’s useful when you’re working with our CE-OpenApi.

CE-OpenApi Method details

Subscribing to our public plan will allow you to make a limited number of requests to the CE-OpenApi. This should be sufficient for exploration purposes.

For more information on the commercial conditions that apply to using our APIs, please contact our sales team at sales@connecting-expertise.com.

Note
 You are an early adopter of our new CE-OpenApi. If you run into a mistake, or can’t find what you’re looking for, please let us know via openapi@connecting-expertise.com.

Getting started

Before you can use our CE-OpenApi let’s explain how you get started.

Get connected

It’s easy to connect with the CE-OpenApi. Follow these 3 steps:

STEP 1

Register your company/user

If you already have a Connecting-Expertise login, you can skip this step. Otherwise, register as a new company/user.

Note
 You may use these CE-VMS environments:
* Development: https://int.connecting-expertise.com
* Production: https://customer.connecting-expertise.com
STEP 2

Apply for access

Once you are able to logon to the CE-VMS, we will need to activate the CE-OpenApi. We can also activate the CE-OpenApi EMI on your request. Please contact us via openapi@connecting-expertise.com.
Subscribing to our public plan will allow you to make a limited number of requests to the CE-OpenApi. This should be sufficient for exploration purposes.
Once you develop a production application that relies on our api services, contact our sales team via sales@connecting-expertise.com.

In return, you’ll receive:

  1. For the CE-OpenApi

    • a client_id (e.g. SupplierApplication_Yik3jkDD7fJJIOKLPSDMaf_)

    • a client_secret (e.g. Q9dd8FDyFg4oeTMAFhDolJKlalaUD2pplosDSU_)

  2. For the CE-OpenApi EMI:

    • a client_id (e.g. Xvz1evFS4wEEPTGEFPHBog_)

    • a client_secret (e.g. L8qq9PZyRg6ieKGEKhZolGC0vJWLw8iEJ66DRdyFHH_)

Caution
 Your client_secret key should not be shared or embedded in client-side code.
STEP 3

Try the CE-OpenApi services and CE-OpenApi EMI

Once your user has access to our CE-OpenApi or CE-OpenApi EMI, you can try out our services.

Note
 You may use these environments for the CE-OpenApi:
- Development: https://openapi-mars.connecting-expertise.com/connectingExpertise/swagger/ce3OpenApi#/
- Production: https://openapi.connecting-expertise.com/connectingExpertise/swagger/ce3OpenApi#/

Building a request

The CE-OpenApi is a collection of 'REST(ful)' webservices. You interact with our resources by sending a message with the HTTPS protocol to a URL. The URL determines the resource and the HTTPS method defines the type of action. Data is passed as JSON in a POST request or as GET query parameters.

URLs

All URLs conform to this pattern:

https://{hostname} /{version} /{area} /[?{option_key}={option_value}]
Table 1. URL composition components
Component Explanation

hostname

The hostname determines whether you access the development- or production environment:
Development environment: https://openapi-mars.connecting-expertise.com/connectingExpertise/swagger/ce3OpenApi#/
Production environment: https://openapi.connecting-expertise.com/connectingExpertise/swagger/ce3OpenApi#/

version

New versions of services can be introduced with additional features. The version number allows you to select a particular service version.

area

The CE-OpenApi is separated into different 'areas':

Master data (e.g. city, company, department, language, location,…​)
Document
Received request
Human resource
Proposal

HTTP method

The HTTP method (GET, PUT, PATCH, POST, DELETE) defines what you want to do with the resource.

Authentication

The CE-OpenApi supports basic authentication and token based authentication. For more information, please check out Authentication for a detailed explanation.

Service request outcome: HAL

The output format of a CE-OpenApi request is HAL, short for "Hypertext Application Language" (See also "Hypertext Application Language").

HAL is an open specification describing a generic structure for RESTful resources. The structure it proposes readily achieves the Richardson Maturity Model’s Level 3, by ensuring that each resource contains relational links, and that a standard, identifiable structure exists for embedding other resources.

Note
 Essentially, good RESTful APIs should:
- expose resources
- via HTTP, using HTTP verbs to manipulate them
- and provide canonical links to themselves, as well as link to other, related resources

HAL was created to be simple to use and easily applicable across different domains by avoiding the need to impose any requirements on structure of the project.
Maintaining this minimal impact approach, HAL has enabled developers to create general-purpose libraries which can be easily incorporated on any API that uses HAL.

APIs that adopt HAL simplify the use of open source libraries and make it possible to interact with the API using JSON or XML.

Connecting-Expertise OpenApi Console

We’ve teamed up with SwaggerHub to provide you with an interactive manual through a REST console. This console allows you to experiment with the CE-OpenApi without writing a single line of code.

Steps to explore our CE-OpenApi

If you like to experiment with our services on the CE-OpenApi, you need to follow these steps:

STEP 1

Visit our CE-OpenApi swagger page

Go to the desired swagger page (choose between development or production).

Note
 We support multiple environments for the CE-OpenApi:
- Development: https://openapi-mars.connecting-expertise.com/connectingExpertise/swagger/ce3OpenApi#/
- Production: https://openapi.connecting-expertise.com/connectingExpertise/swagger/ce3OpenApi#/
STEP 2

Select the "HTTPS" scheme (picklist on the left)

OpenApiConsole

STEP 3

“Authorize” (green button on the right)

OpenApiConsole Authorize

STEP 4

Enter credentials

Choose the desired authentication method (For more information, please check out Authentication).
With basic authentication, enter the credentials that you used to register yourself:

  • Username: your Connecting-Expertise login name

  • Password: your Connecting-Expertise password

    OpenApiConsole BasicAuthorization

STEP 5

Explore the CE-OpenApi

Click "Authorize" and you’re all set to explore our CE-OpenApi. It serves as an access point to your own CE-VMS environment.

Essentials

Authentication

The CE-OpenApi supports basic authentication and token based authentication. The CE-OpenApi EMI supports only token based authentication.

Note
 An access token is a string representing the granted permissions.

Basic authentication

We allow basic authentication on our develop environment, but as soon as you want to integrate with our production environment, you’ll have to use the token based approach.

Note
 Basic authentication is a simple authentication scheme built into the HTTPS protocol. Your client sends HTTPS requests with the Authorization header that contains the word Basic word followed by a space and a base64-encoded string username:password.

Example: to authorize as 'demo' / 'p@55w0rd', your client should send:

Authorization: Basic ZGVtbzpwQDU1dzByZA

Token based authentication

Even though you are able to use basic authentication to explore services for the CE-OpenApi on our development environment, you’ll have to use a token based approach as soon as you want to connect to our production environment, or use the CE-OpenApi EMI.
Token based authentication, which uses a bearer token, is also known as application-only authentication.

Note
 Token based authentication consists of 2 steps:
- obtain a valid bearer token
- use a valid bearer token in your api requests
Obtain a valid bearer token

First of all we’ll need to set up access for your application account to the CE-OpenApi or CE-OpenApi EMI (Refer to Get connected).

With your own client_id your application is able to get an authorization code (not an authentication token!).
After receiving an authorisation code, your application exchanges this for an access token and a refresh token.

Note
 An authorization code can only be exchanged once for an access token and expires 10 minutes after issuance.

These access tokens are also known as bearer tokens. You can use this token to call API endpoints on behalf of a user, by adding it to the API request as an Authorization header.

This 2-step authentication flow is necessary for security reasons.

Access tokens expire shortly after they are issued for security reasons. If your integration needs to communicate with our API beyond the access token’s lifespan, you will need to request a new access token using the refresh token which was issued with the access token. Note that refresh tokens can only be used once to get a new access token and refresh token.

Example: request a CE-OpenApi bearer token

Here’s an example of how your OIDC settings for the issuing of a CE-OpenApi bearer token might look like:

{
"authority": "https://auth-nonprod.connecting-expertise.com/realms/openapi-mars/protocol/openid-connect/token",
"redirectUri": "http://localhost:8082/oidc-callback", // (1)
"responseType": "token",
"scope": "openid profile",
"client_id": "SupplierApplication_Yik3jkDD7fJJIOKLPSDMaf_", // (2)
"client_secret": "Q9dd8FDyFg4oeTMAFhDolJKlalaUD2pplosDSU_" // (3)
}

  1. Replace with your own url

  2. Replace with your own client_id

  3. Replace with your own client_secret

Result:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqb19wZC1HeHMxQUZscUhvNGUxMXo5Zm9sN083aFAzMVhjMS1fYmhabENRIn0eyJleHAiOjE2NDAxMTQ2MDksImlhdCI6MTY0MDExNDMwOSwianRpIjoiNTJhZGE5ZTQtNTQyZS00MTc2LWJiMWUtZGVlZDFmNzI2Y2Y3IiwiaXNzIjoiaHR0cHM6Ly9hdXRoLW5vbnByb2QuY29ubmVjdGluZy1leHBlcnRpc2UuY29tL2F1dGgvcmVhbG1zL2RldmVsb3AiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiYzRmMTNjNTYtNzhmYi00Y2RhLTg3NDQtYmVmM2Y5OGUxNDZlIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoic3VwcGxpZXJUZXN0Iiwic2Vzc2lvbl9zdGF0ZSI6IjgzYjc3ZGM0LWEyMjItNGY5MS1hYzIwLWQyYTE3YjdiNTU0ZCIsImFjciI6IjEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiZGVmYXVsdC1yb2xlcy1kZXZlbG9wIiwib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiJJKIOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicHJvZmlsZSBlbWFpbCIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhcGlAY29udGluZ2VudC5jb20iLCJlbWFpbCI6FDFwaUBjb250aW5nZW50LmNvbSJ9eQacAr_tvEgHrIQpE5vzhp1yDXpv_QDviFWr6Rf2zWJD_mBFA12S25cu3qq8fZq9NtHpvg6nhQ2hbilHHLez3g3YiuZKu1ZG6pf9dwQ1w0TMOEDxIgWduMHt_g0r9YCCHmy3y1Af5rIeq3g8_uySQ1iSJy9IKWMeGaHfRBmrhaalu0UU5jzKy4vEXc81TDtDVMP2vdwJUwxoQTsHEcdw3Ul024qonxOcUHRCs1pIOiu2d_ViRgdf9P0DPiWfPdYuoheUJQHoTPTChuXYCXtjTRwLZAcuySUUeORVb7ty7WXD0wkKJjQTMgg5yGrw9wn5iOl4ByCLHdUw",
    "expires_in": 600,
    "refresh_expires_in": 1800,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIxMjQyZjA4Ni04YTgyLTQ1NjAtYWI3My0wYWVhMTUzNDk0ZDYifQeyJleHAiOjE2NDAxMTYxMDksImlhdCI6MTY0MDExNDMwOSwianRpIjoiZDg1MGU2ZjAtOWY4My00M2ZjLThjZDktZTFjYWM3MzJkZWE1IddjkiiaXNzIjoiaHR0cHM6Ly9hdXRoLW5vbnByb2QuY29ubmVjdGluZy1leHBlcnRpc2UuY29tL2F1dGgvcmVhbG1zL2RldmVsb3AiLCJhdWQiOiJodHRwczovL2F1dGgtbm9ucHJvZC5jb25uZWN0aW5nLWV4cGVydGlzJKKIoZS5jb20vYXV0aC9yZWFsbXMvZGV2ZWxvcCIsInN1YiI6ImM0ZjEzYzU2LTc4ZmItNGNkYS04NzQ0LWJlZjNmOThlMTQ2ZSIsInR5cCI6IlJlZnJlc2giLCJhenAiOiJzdXBwbGllclRlc3QiLCJzZXNzaW9uX3N0YXRlIjoiODNiNzdkYzQtYTIyMi00ZjkxLWFjMjAtZDJhMTdiN2I1NTRkIiwic2NvcGUiOiJwcm9maWxlIGVtYWlsIn0.pQtvnimnCeUXKvZcClMCZe9SWdkYRuRgcES2sQ10yzY",
    "token_type": "Bearer",
    "not-before-policy": 1638266634,
    "session_state": "83b77dc4-a222-4f91-ac20-d2a17b7b554d",
    "scope": "profile email"
}
Authentication environments

These are the urls you can use to obtain valid bearer tokens for your requests or {openApiEventMessageInbox}.

Purpose Environment Url

CE-OpenApi

development

https://auth-nonprod.connecting-expertise.com/realms/openapi-mars/protocol/openid-connect/token

production

https://auth.connecting-expertise.com/realms/openapi/protocol/openid-connect/token

CE-OpenApi EMI

development

https://auth-nonprod.connecting-expertise.com/realms/emi-mars/protocol/openid-connect/token

production

https://auth.connecting-expertise.com/realms/emi/protocol/openid-connect/token
Accessing a CE-OpenApi endpoint with a valid token

Every REST API request needs a valid bearer token (other option(s) are available, but we don’t promote them).
Without a valid token a request sent to the REST API will result in an authorization error.

When you use the token based authentication flow, your client sends HTTPS requests with the Authorization header that contains the word Bearer followed by a space and valid token.

Example: to authorize your application, your client should send:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqb19wZC1HeHMxQUZscUhvNGUxMXo5Zm9sN083aFAzMVhjMS1fYmhabENRIn0eyJleHAiOjE2NDAxMTQ2MDksImlhdCI6MTY0MDExNDMwOSwianRpIjoiNTJhZGE5ZTQtNTQyZS00MTc2LWJiMWUtZGVlZDFmNzI2Y2Y3IiwiaXNzIjoiaHR0cHM6Ly9hdXRoLW5vbnByb2QuY29ubmVjdGluZy1leHBlcnRpc2UuY29tL2F1dGgvcmVhbG1zL2RldmVsb3AiLCJhdWQiOiJhY2NvdW50Iiwic3ViIjoiYzRmMTNjNTYtNzhmYi00Y2RhLTg3NDQtYmVmM2Y5OGUxNDZlIiwidHlwIjoiQmVhcmVyIiwiYXpwIjoic3VwcGxpZXJUZXN0Iiwic2Vzc2lvbl9zdGF0ZSI6IjgzYjc3ZGM0LWEyMjItNGY5MS1hYzIwLWQyYTE3YjdiNTU0ZCIsImFjciI6IjEiLCJyZWFsbV9hY2Nlc3MiOnsicm9sZXMiOlsiZGVmYXVsdC1yb2xlcy1kZXZlbG9wIiwib2ZmbGluZV9hY2Nlc3MiLCJ1bWFfYXV0aG9yaXphdGlvbiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicHJvZmlsZSBlbWFpbCIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhcGlAY29udGluZ2VudC5jb20iLCJlbWFpbCI6FDFwaUBjb250aW5nZW50LmNvbSJ9eQacAr_tvEgHrIQpE5vzhp1yDXpv_QDviFWr6Rf2zWJD_mBFA12S25cu3qq8fZq9NtHpvg6nhQ2hbilHHLez3g3YiuZKu1ZG6pf9dwQ1w0TMOEDxIgWduMHt_g0r9YCCHmy3y1Af5rIeq3g8_uySQ1iSJy9IKWMeGaHfRBmrhaalu0UU5jzKy4vEXc81TDtDVMP2vdwJUwxoQTsHEcdw3Ul024qonxOcUHRCs1pIOiu2d_ViRgdf9P0DPiWfPdYuoheUJQHoTPTChuXYCXtjTRwLZAcuySUUeORVb7ty7WXD0wkKJjQTMgg5yGrw9wn5iOl4ByCLHdUw
...

Schematic representation:

Authentication OpenApi

Using refresh tokens

If an access token is expired, a new access token and refresh token pair can be obtained.

Acting "on behalf of"

Acting on behalf of allows a (middleware) application to authenticate on the CE-OpenApi with an "authentication user", and to perform the actual business actions "on behalf of a business user".

By using this pattern, the (middleware) application doesn’t need to know/use the actual business user credentials to authenticate in the CE-VMS. The (middleware) application authenticates by using it’s own credentials and adds the acting on behalf of information to the CE-OpenApi-call to communicate the actual business user to the CE-VMS.

Example

ActingOnBehalfOf

STEP 1

Create an ATS candidate

'Jean Dockx', an employee of supplier company 'Suppliers inc.', creates a Candidate in his own ATS system, called 'Suppliers inc. ATS'.

'Jean Dockx' is also registered as a CE-VMS user with:

  • Uuid: '47c3dd2c-a9b2-11ec-8857-525400c4a10a'

  • Username: 'jean.dockx@suppliers-inc.com'

  • Reference:

    • Source system = 'Suppliers inc. ATS'

    • external reference = 'JEAN_34J3K4JM_FH'

STEP 2

The middleware creates a C-E HumanResource

The middleware application uses our CE-OpenApi to create a CE-VMS HumanResource for the new 'Suppliers inc. ATS' Candidate.

Therefore, the middleware:

  • Authenticates with a CE-VMS authentication user ('api@suppliers-inc.com')

  • Creates a CE-VMS Human Resource on behalf of business user 'Jean Dockx' with:

    • Acting-On-Behalf-Of-External-User = 'JEAN_34J3K4JM_FH:Suppliers inc. ATS' Or

    • Acting-On-Behalf-Of-User = '47c3dd2c-a9b2-11ec-8857-525400c4a10a'

STEP 3

The outcome

A new CE-VMS HumanResource, created by user 'jean.dockx@suppliers-inc.com'.

How to use the "acting on behalf of" feature?

There are two options to communicate the acting on behalf of-business user to the CE-OpenApi:

  • Acting-On-Behalf-Of-User: refers to the uuid of the business user

  • Acting-On-Behalf-Of-External-User: refers to the external reference of the business user.

    • Layout:

externalReference:sourceSystem
Important
 An authentication user can only act on behalf of a business user if it has been set up in the CE-VMS. If you would like to use this feature and/or adjust the setup, please contact us via {openapi@connecting-expertise.com}.

Connecting-Expertise OpenApi Event Message Inbox

In the CE-VMS events may occur. An event could be the publication of a request, the selection of a candidate, a timesheet that requires approval, …​

Let’s say that you’re interested in the Proposal selection process, and that you would like to be informed each time a selection step (=application event on a Proposal) has occurred.

One approach could be to use the Proposal history-endpoint in a recurring fashion. Check for example each hour if new events have occurred, and process them.
But our preferred solution is to subscribe to our CE-OpenApi EMI. Each CE-VMS application event is published to a message inbox. And you’ll be notified when a new message has been published.

Start using the CE-OpenApi EMI

To use the CE-OpenApi EMI, you’ll need to follow these steps:

STEP 1

Register your application
If you have an active user account on the CE-VMS, we can activate the CE-OpenApi EMI for you. Please contact us via openapi@connecting-expertise.com, and we’ll get back to you with your application’s client id and client secret.

STEP 2

Setup a consumer
From the moment we activate your CE-OpenApi EMI, every CE-VMS application event is stored as 1 unique message in your CE-OpenApi EMI-inbox. It’s up to you which messages you’re interested in: the entire CE-OpenApi EMI, or only a subset(s) of it.

STEP 3

Subscribe to your CE-OpenApi EMI
The CE-OpenApi EMI requires subscription with your dedicated CE-OpenApi EMI client id and client secret, and the usage of a filter to access your event messages.
Each subscription will result in 1 CE-OpenApi EMI subset (= a queue), and you decide how finely meshed your CE-OpenApi EMI subset(s) are.

Note
 There are 3 possible filtering options:
- all messages
- all messages from 1 specific Application Context (e.g. PROPOSAL)
- all messages from 1 specific Application Event (e.g. CREATE)
STEP 4

Start processing event messages
Once we’ve activated your CE-OpenApi EMI account and you subscribed to (parts) of your CE-OpenApi EMI, we’ll start saving every application event occurrence as 1 unique event message.
Remark: we’ve adopted QoS 1 (at least once) semantics. While your client is permitted to request QoS 2 subscription, the adapter will only grant subscription up to QoS 1.

Important
 We make a distinction between these environments for the CE-OpenApi EMI:
- CE-OpenApi EMI Development: emi-mars.connecting-expertise.com
- CE-OpenApi EMI Production: emi.connecting-expertise.com
Schematic representation: CE-OpenApi EMI usage

This schema shows you how to use the CE-OpenApi EMI: