Page Comparison

A typical application integration requires to store a mapping your application records IDs with the external application IDs, in this case the Connec!™ IDs.

Connec!™ proposes the option to store third-party systems IDs it integrates with. This can simplifies the integration with Connec!™ as an external application no longer requires to store the mapping of IDs between the 2 systems.

Table of Contents

Scenarios

Your application may already support native integrations with other existing applications outside the Maestrano platform. Supposing one of your customers starts using Maestrano integration services and connects these 2 applications on the Maestrano platform, records may be replicated inside the 2 applications creating duplicates. To avoid this scenario, all the external IDs coming from the applications ecosystems are exposed so records can be merged.

API operations

When fetching data from the API, the request header CONNEC-EXTERNAL-IDS can be set to ask Connec!™ to return the known external systems IDs.

Fetch a collection

Code Block
GET https://api-connec.maestrano.com/api/v2/cld-1234/people Headers CONNEC-EXTERNAL-IDS: true

Response

Code Block

collapse	true

{
  "people": [
    {
      "id": [
        {
          "realm": "2243",
          "provider": "my-external-app",
          "id": "1"
        },
        {
          "realm": "org-abcd",
          "provider": "connec",
          "id": "7fef3180-6bf8-0134-2d52-2f659c5af2a1"
        }
      ],
      "code": "PE1",
      "status": "ACTIVE",
      "title": "Dr.",
      "first_name": "Anastasia",
      "last_name": "Brekke",
      "job_title": "Chief Directives Engineer",
      "birth_date": "1985-01-29T00:00:00Z",
      "organization_id": [
        {
          "realm": "2243",
          "provider": "my-external-app",
          "id": "47"
        },
        {
          "realm": "org-abcd",
          "provider": "connec",
          "id": "7fe83950-6bf8-0134-2d50-2f659c5af2a1"
        }
      ],
      "email": {
        "address": "dexter@lakin.com"
      },
      "created_at": "2016-10-04T00:36:23Z",
      "updated_at": "2016-10-04T00:36:23Z",
      "group_id": "cld-1234",
      "channel_id": "org-abcd",
      "resource_type": "people"
    },
    {
      "id": [
        {
          "realm": "org-abcd",
          "provider": "connec",
          "id": "7ff80260-6bf8-0134-2d54-2f659c5af2a1"
        }
      ],
      "code": "PE2",
      "status": "ACTIVE",
      "title": "Mrs.",
      "first_name": "Gretchen",
      "last_name": "Kris",
      ...
    }
  ],
  "pagination": {
    "skip": 0,
    "top": 100,
    "total": 2
  }
}

Fetch a single resource

To fetch a single resource using a specific external system ID, the parameters opts[provider] and opts[realm] can be specified.

Code Block
GET https://api-connec.maestrano.com/api/v2/cld-1234/people/1?opts[provider]=my-external-app&opts[realm]=2243 Headers CONNEC-EXTERNAL-IDS: true

Response

Code Block

collapse	true

{
  "people": {
    "id": [
      {
        "realm": "2243",
        "provider": "my-external-app",
        "id": "1"
      },
      {
        "realm": "org-abcd",
        "provider": "connec",
        "id": "7fef3180-6bf8-0134-2d52-2f659c5af2a1"
      }
    ],
    "code": "PE1",
    "status": "ACTIVE",
    "title": "Dr.",
    "first_name": "Anastasia",
    "last_name": "Brekke",
    "job_title": "Chief Directives Engineer",
    "birth_date": "1985-01-29T00:00:00Z",
    "organization_id": [
      {
          "realm": "2243",
          "provider": "my-external-app",
          "id": "47"
        },
        {
        "realm": "org-abcd",
        "provider": "connec",
        "id": "7fe83950-6bf8-0134-2d50-2f659c5af2a1"
      }
    ],
    "email": {
      "address": "dexter@lakin.com"
    },
    "website": {
      "url": "http://schaden.com/urban"
    },
    "created_at": "2016-10-04T00:36:23Z",
    "updated_at": "2016-10-04T00:36:23Z",
    "resource_type": "people",
    "group_id": "cld-1234",
    "channel_id": "org-abcd",
  }
}

Create or Update a resource

If any of the specified external_ids is matched, the matching resource will be updated. Otherwise a new resource with these external_ids is created

Code Block

collapse	true

POST https://api-connec.maestrano.com/api/v2/cld-1234/people
Headers
  CONNEC-EXTERNAL-IDS: true

Request:
{
  "people": {
    "id": [
      {
        "realm": "2243",
        "provider": "my-application",
        "id": "17"
      }
    ],
    "title": "Mr.",
    "first_name": "Bob",
    "last_name": "Builder",
    "organization_id": [
      {
        "realm": "2243",
        "provider": "my-application",
        "id": "4"
      }
    ]
  }
}

Response:

Code Block

collapse	true

{
  "people": {
    "id": [
      {
        "realm": "2243",
        "provider": "my-application",
        "id": "17"
      },
      {
        "realm": "org-abcd",
        "provider": "connec",
        "id": "8400ddc0-70ab-0134-fc40-74d43510c326"
      }
    ],
    "code": "PE136",
    "status": "ACTIVE",
    "title": "Mr.",
    "first_name": "Bob",
    "last_name": "Builder",
    "organization_id": [
      {
        "realm": "2243",
        "provider": "my-application",
        "id": "4"
      },
      {
        "realm": "org-abcd",
        "provider": "connec",
        "id": "7fe83950-6bf8-0134-2d50-2f659c5af2a1"
      }
    ],
    ..."created_at": "2016-10-10T00:07:54Z",
    "updated_at": "2016-10-10T00:07:54Z",
    "group_id": "org-fbba",
    "channel_id": "org-fbba",
    "resource_type": "people"
  }
}

Versions Compared

Old Version 4

New Version 5

Key

Scenarios

API operations

Fetch a collection

Fetch a single resource

Create or Update a resource