Connector Tenant Messagelog API
by sanjeevgiri

Connector Tenant Messagelog API

Documentation
Connector Tenant Messagelog API Reference

Overview

Connector Tenant Messagelog API may be used to manage persistance and visibility of artibrary message payloads.

Target clients

  • Thin connectors
  • Gateway component

End Users (Persona)

  • Customer administrators

API Dependencies

  • None

Description of terms used

  • Client: Vertex customer
  • Tenant: Vertex customer’s subscription to a specific regional product
  • Partner Tenant: Vertex customer’s subscription for a specific partner product (Exampel - SAP US, Ariba2 Canada …)
  • Vertex Connector Administrator: Internal vertex user that is capable of managing global connector settings.
  • Integration: An identifier for describing a machine to machine communication between partner systems and vertex core products.

API Access

  • API endpoints can be accessed by authorized users by obtaining bearer tokens from configured idP.
  • API endpoints will be internally available over the VPN/VPC for vertex connector administrators.

Versioning

  • Current Version: 0.0.1
  • This API will be versioned using semantic versioning and will maintain backward compatibility among patch and minor versions for the given major version.

Monitoring

  • For monitoring purposes, we are recommending each connector to implement a public health check endpoint using the path /health. The API must include status of the external components it is integrating with (partner endpoint, vertex product endpoint, databases, fileservers…).
  • Centralized tenant specific integration status page may be exposed to vertex connector administrator.
  • Alerts may be configured based on the integration health checks
Models
BaseProblem

A Problem Details object RFC 7807

Object
type
string uri

A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be “about:blank”.

Example:
https://speca.io/sanjeevgiri/connector-administration-api#BaseProblem
title
string

A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see [RFC7231], Section 3.4).

Example:
Service Unavailable
status
integer int32

The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.

Min: 400
Max: 600
exclusive
Example:
503
detail
string

A human-readable explanation specific to this occurrence of the problem.

Example:
Service Unavailable. Please try again later.
instance
string

A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

Example:
connector-admin-api-5868d8969f-zrz4z
timestamp
string date-time

Extention property specifying the time the problem was encountered

Example:
2022-10-28T18:39:21Z
traceId
string uuid

Extension property. Problem identifier to help querying internal log system for further details

Example:
e68cae3b-3c77-4fed-93d3-1765c24fd6e8
ecnounteredBy
string

Extension property. User or machine client that ovsreved this error.

Example:
vertexConnectorAdminUser1@vertexinc.com
BaseResource
Object
id
string uuid

Resource identifier

Example:
9fe70c57-4815-4247-8ec8-0d886277e93a
version
integer int64

Resource version. This value is recommended to have incremental characteristics, and may be used for communicating changes over time as well as optimistic locking.

Examples:
12
createdAt
string date-time

Timestamp (UTC recommended) the resources was created.

Example:
2022-10-28T18:39:21Z
updatedAt
string date-time

Timestamp (UTC recommended) the resource was updated. For a newly created resource, this will be the same value as the createdAt property. This property may be used as the default sort field in descending order for operations that require paging across resources.

Example:
2022-10-29T18:39:21Z
createdBy
string

User identifier that initiated the creation of a given resource.

Example:
vertexConnectorAdminUser1@vertexinc.com
updatedBy
string

User identifier that initiated the modification of a give resource. For a newly created resource, this is expected to be the same value as the createdBy property.

Example:
vertexConnectorAdminUser2@vertexinc.com
Connector

Identifier for a software component that facilitates communication between partner and vertex offered service.

string
Enumeration:
BIGCOMMERCE_OSERIES
SAPTAXSERVICE_OSERIES
ARIBA2_OSERIES
TenantMessagelogPayload

Represents tenant specific message log

Object
client
string uuid

Vertex customer internal identifier

Example:
cd671e55-9575-4a25-8b1b-2e85b5867059
clientName
string

Vertex customer name

Example:
Company xyz
tenant
string uuid
Example:
1a855cf0-d29b-4fb2-a238-abd2c0d03856
tenantName
string
Example:
Company xyz (North America)
tenantApiEndpoint
string

Tenant specific vertex core product endpoint for this integration

Example:
https://productxyz-api@vertexinc.com
partnerTenant
string

Vertex customer subscription identifier in partner system. It is preferable to have uniqueness for this attribute. However, value may originate from partner system and we can assume uniqueness cannot be gauranteed by this property alone.

Example:
4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee
partnerTenantName
string
Example:
Partner product 123 for Company xyz (North America)
partnerTenantApiEndpoint
string uri

Partner API endpoint (Not required if not being used by the integration)

Example:
https://product123-api@partnersite.com
connector
Connector

Identifier for a software component that facilitates communication between partner and vertex offered service.

Example:
BIGCOMMERCE_OSERIES
tenantIntegrationId
string uuid
Example:
9fe70c57-4815-4247-8ec8-0d886277e93a
messageLog
string

Recommended to exclude sensitive data. Depending on the type of message, the API may perform some scrubbing as well.

Example:
<QuotationRequest>....<QuotationRequest>
messageType
string

Message type that specifies the structure of the message log.

Examples:
OSERIES_QUOTE_REQUESTBIGCOMMERCE_QUOTE_REQUEST
expiresAt
string date-time

Timestamp when the message will be eligible for pruning

tags
Array of string

Tags associated with the message.

Unique items: YES
Example: 
[
    "documentNumber:123", "customerId:abc"
]
show more
TenantMessagelog
All of
Example: 
{
    "id": "9fe70c57-4815-4247-8ec8-0d886277e93a",
    "version": 2,
    "createdAt": "2022-10-28T18:39:21Z",
    "updatedAt": "2022-10-28T18:39:21Z",
    "createdBy": "vertexConnectorAdminUser1@vertexinc.com",
    "updatedBy": "vertexConnectorAdminUser2@vertexinc.com",
    "client": "cd671e55-9575-4a25-8b1b-2e85b5867059",
    "clientName": "Company xyz",
    "tenant": "1a855cf0-d29b-4fb2-a238-abd2c0d03856",
    "tenantName": "Company xyz (North America)",
    "tenantApiEndpoint": "https://productxyz-api@vertexinc.com",
    "partnerTenant": "4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee",
    "partnerTenantName": "Partner product 123 for Company xyz (North America)",
    "partnerTenantApiEndpoint": "https://product123-api@partnersite.com",
    "connector": "BIGCOMMERCE_OSERIES",
    "tenantIntegrationId": "9fe70c57-4815-4247-8ec8-0d886277e93a",
    "messageLog": "<QuotationRequest>....<QuotationRequest>",
    "messageType": "BIGCOMMERCE_QUOTE_REQUEST",
    "expiresAt": "2022-11-29T18:39:21Z",
    "tags": [
        "documentNumber:123", "customerId:abc"
    ]
}
BaseResource
TenantMessagelogPayload
Headers
OAuth2
Authorization
string required
Applied to all operations
Example:
Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Parameters
Pagination
pageSort
string optional

Multi value sort parameter used for paging across a large data set. The expected format is as follows when specified:

sortField,sortOrder

sortField can be any arbitrary field specific to the content that is being paged sortOrder is ASC or DESC. The sort order defaults to ASC when left unspecified.

A page can be sorted using multiple columns by providing multiple sort query parameters

/path/resource?pageSort=field1,ASC&pageSort=field2,DESC
Default:
updatedAt,DESC
Examples:
updatedAt,DESCcreatedAt,ASC
pageSize
integer int32 optional

Requested number of elements in a given page or results

Allow empty value: true
Min: 1
Max: 100
Default:
20
pageNumber
integer int32 optional
Allow empty value: true
Default:
0
Example:
10
Operations
Manage Tenant Messagelogs
Create
POST /tenantintegrations/{tenantintegrationid}/tenantmessagelogs
List
GET /tenantintegrations/{tenantintegrationid}/tenantmessagelogs
Create
POST /tenantintegrations/{tenantintegrationid}/tenantmessagelogs

Authentication

OAuth
ConnTenantMessagelogApi:TenantMessagelog:Write

This API may be proxied through a gateway component that derives the tenant integration id and tenancy details using partner tenant id and connector name. Do we need to validate the tenant integration id details?

Path variables

tenantintegrationid
string required

Request body

Array of TenantMessagelogPayload

Responses

204 No Content
204
POST https://conn-tenant-messagelog-api.platdev.vtxdev.net/tenantintegrationid/9fe70c57-4815-4247-8ec8-0d886277e93a/tenantmessagelogs HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Content-Type: application/json
[
    {
        "client": "cd671e55-9575-4a25-8b1b-2e85b5867059",
        "clientName": "Company xyz",
        "tenant": "1a855cf0-d29b-4fb2-a238-abd2c0d03856",
        "tenantName": "Company xyz (North America)",
        "tenantApiEndpoint": "https://productxyz-api@vertexinc.com",
        "partnerTenant": "4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee",
        "partnerTenantName": "Partner product 123 for Company xyz (North America)",
        "partnerTenantApiEndpoint": "https://product123-api@partnersite.com",
        "connector": "SAPTAXSERVICE_OSERIES",
        "tenantIntegrationId": "9fe70c57-4815-4247-8ec8-0d886277e93a",
        "messageLog": "<QuotationRequest>....<QuotationRequest>",
        "messageType": "OSERIES_QUOTE_REQUEST",
        "expiresAt": "2022-11-28T18:39:21Z",
        "tags": [
            "documentNumer:abc", "customerId:123"
        ]
    }
]

HTTP/1.1 204 No Content
show more
List
GET /tenantintegrations/{tenantintegrationid}/tenantmessagelogs

Authentication

OAuth
ConnTenantMessagelogApi:TenantMessagelog:Read

Path variables

tenantintegrationid
string required

Request parameters

pageSort
string optional

Multi value sort parameter used for paging across a large data set. The expected format is as follows when specified:

sortField,sortOrder

sortField can be any arbitrary field specific to the content that is being paged sortOrder is ASC or DESC. The sort order defaults to ASC when left unspecified.

A page can be sorted using multiple columns by providing multiple sort query parameters

/path/resource?pageSort=field1,ASC&pageSort=field2,DESC
Default:
updatedAt,DESC
Examples:
updatedAt,DESCcreatedAt,ASC
pageSize
integer int32 optional

Requested number of elements in a given page or results

Allow empty value: true
Min: 1
Max: 100
Default:
20
pageNumber
integer int32 optional
Allow empty value: true
Default:
0
Example:
10
tags
array of string optional

Tags associated with messag log. Query results must include records that match all tags (ANDED)

Collection format: csv

Responses

200 OK
Body
Array of TenantMessagelog
Example 1
GET https://conn-tenant-messagelog-api.platdev.vtxdev.net/tenantintegrations/9fe70c57-4815-4247-8ec8-0d886277e93a/tenantmessagelogs HTTP/1.1 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

HTTP/1.1 200 OK 

Content-Type: application/json

[
    {
        "id": "f5589992-281c-49f8-8ce5-a5631beee522",
        "version": 1,
        "createdAt": "2022-10-28T18:39:21Z",
        "updatedAt": "2022-10-28T18:39:21Z",
        "createdBy": "vertexConnectorAdminUser1@vertexinc.com",
        "updatedBy": "vertexConnectorAdminUser2@vertexinc.com",
        "client": "cd671e55-9575-4a25-8b1b-2e85b5867059",
        "clientName": "Company xyz",
        "tenant": "1a855cf0-d29b-4fb2-a238-abd2c0d03856",
        "tenantName": "Company xyz (North America)",
        "tenantApiEndpoint": "https://productxyz-api@vertexinc.com",
        "partnerTenant": "4d6696e4-f2cb-4eb3-8d8b-15fdd19bf4ee",
        "partnerTenantName": "Partner product 123 for Company xyz (North America)",
        "partnerTenantApiEndpoint": "https://product123-api@partnersite.com",
        "connector": "SAPTAXSERVICE_OSERIES",
        "tenantIntegrationId": "9fe70c57-4815-4247-8ec8-0d886277e93a",
        "messageLog": "<QuotationRequest>....<QuotationRequest>",
        "messageType": "BIGCOMMERCE_QUOTE_REQUEST",
        "expiresAt": "2022-11-28T18:39:21Z",
        "tags": [
            "documentNumber:abc", "customerId:123"
        ]
    }
]
show more