Skip to main content

Create an integration configuration

Important

This feature is currently in Early Availability (EA) status. For more information, see GraphQL API policy.

When activity in the marketplace generates an event for a product, the marketplace sends a notification to the product host so that it can respond appropriately to the event. For example, when a customer buys a product, the marketplace generates an event. It notifies the product host to create a new subscription for the customer by sending a message to a URL designated for subscription creation messages. This is achieved through a product integration configuration, which is a collection of configurations that define how to handle notifications for events related to products. You can link multiple products to the same integration configuration.

To create an integration configuration, follow these steps:

1. Create an integration configuration​

Define a set of URLs that will receive event notifications for the product and the fields to be collected during a purchase. Use the createProductIntegration mutation to create an productIntegration object.

An integration configuration specifies URLs for different events (create, upgrade, cancel, and so on). Depending on how the product host is set up you can specify a different URL for each type of event, or simply use the same URL for all of them.

Mutation​

mutation {
  createProductIntegration(
    input: {
      createUrl: "https://example.com/notifications"
      upgradeUrl: "https://example.com/notifications"
      cancelUrl: "https://example.com/notifications"
      notifyUrl: "https://example.com/notifications"
      eventStatusUrl: "https://example.com/notifications"
      assignUrl: "https://example.com/notifications"
      unassignUrl: "https://example.com/notifications"
      name:"Documentation Test Integration",
      outboundCredentials: {
        type: OAUTH2
        clientId: "123456"
        clientSecret: "S3cre1!"
        tokenUri: "http://dummmy.url/api/token"
        grantType: client_credentials
      }
    }
  ) {
    productIntegration {
      id
    }
  }
}

Response​

{
  "data": {
    "createProductIntegration": {
      "productIntegration": {
        "id": "5f157a26-0238-4f3f-9c31-1f3e65b4713e"
      }
    }
  }
}

2. Configure authentication​

Add SSO configuration. This is how users are authenticated to access the product. The following are the available options:

If your product doesn't support SSO, use the Bookmark configuration, this will provide the user a link to the product.

Mutation​

mutation {
  addProductIntegrationOpenIdConnectConfiguration(
    input: {
      integrationConfigurationId: 34827
      clientCreationMethod: "PER_SUBSCRIPTION"
      grantTypes: ["AUTHORIZATION_CODE"]
      redirectUrls: ["YOUR_REDIRECT_URLS"]
      allowOidcScope: false
      allowUserScopes: false
      allowRoleScopes: false
      initiateLoginUrl: "YOUR_INITIATE_LOGIN_URL"
      logoutUrl: "YOUR_LOGOUT_URL"
    }
  ) {
    openIdConnectConfiguration {
      clientCreationMethod
      grantTypes
      redirectUrls
    }
  }
}

Response​

{
  "data": {
    "openIdConnectConfiguration": {
      "clientCreationMethod": "PER_SUBSCRIPTION",
      "grantTypes": [
        "AUTHORIZATION_CODE"
      ],
      "redirectUrls": [
        "YOUR_REDIRECT_URLS"
      ]
    }
  }
}

3. Generate the inbound client​

In order to allow the vendor to respond to an integration event, you will need to create an inbound client and get the credentials. Use the generateProductIntegrationInboundClient mutation.

Mutation​

mutation {
  generateProductIntegrationInboundClient(
    input: { id: "5f157a26-0238-4f3f-9c31-1f3e65b4713e" }
  ) {
    productIntegrationInboundClient {
      clientId
      clientSecret
      createdOn
    }
  }
}

Response​

{
  "data": {
    "productIntegrationInboundClient": {
      {
        "clientId": "X1Btx1eCAT",
        "clientSecret": "dFLdVmedfXSrMMuSjR",
        "createdOn": 1689287082000
      }
    }
  }
}

4. Trigger ping tests​

You can trigger ping tests only for the supported integration endpoints. triggerProductIntegrationPingTest (Optionally) If you query the product, after triggering the ping tests, there is a lastTest object that can be requested as part of the payload and will contain the results of the ping tests. ProductIntegrationTest

Mutation​

mutation {
  triggerProductIntegrationPingTest(
    input: {
      id: "5f157a26-0238-4f3f-9c31-1f3e65b4713e"
      version: WORKING
      eventTypes: [SUBSCRIPTION_ORDER]
    }
  ) {
    productIntegration {
      id
      version
      type
    }
  }
}

Response​

{
  "data": {
    "productIntegration": {
      {
        "id": "5f157a26-0238-4f3f-9c31-1f3e65b4713e",
        "version": "WORKING",
        "type": "FULL_INTEGRATION"
      }
    }
  }
}

5. Publish the integration configuration​

Publish and integration configuration to create a snapshot that is ready to use. So the integration configuration is unaffected when you execute changes. Use the publishProductIntegration mutation.

Mutation​

mutation {
    publishProductIntegration(
      input: {
        integrationId: "5f157a26-0238-4f3f-9c31-1f3e65b4713e"
      }
    ) {
      productIntegration {
        id
        version
      }
  }
}

Response​

{
  "data": {
    "productIntegration": {
      "id": "06ea7f9d-4a1b-4a00-810f-089ac43972e2",
      "version": "PUBLISHED"
    }
  }
}

After you publish the integration configuration, you can link it to one or more products. This is useful if you have multiple products that use the same set of endpoints.

When you link more than one product to an integration configuration, you can no longer modify that integration configuration from the marketplace UI. From then on, you can only modify it using GraphQL APIs. The integration still appears in the product definition in the UI, but it is read-only. This prevents anyone from making a change to the integration in one product and accidentally affecting many other products that use the same template.

Mutation​

mutation {
  linkProductIntegration(
    input: {
      productId: "06ea7f9d-4a1b-4a00-810f-089ac43972e2"
      integrationId: "5f157a26-0238-4f3f-9c31-1f3e65b4713e"
    }
  ) {
    product {
      id
      version
    }
  }
}

Response​

{
  "data": {
    "product": {
      "id": "06ea7f9d-4a1b-4a00-810f-089ac43972e2",
      "version": "WORKING"
    }
  }
}

Was this page helpful?

Tell us more…

Help us improve our content. Responses are anonymous.

Thanks

We appreciate your feedback!