Push API Usage Example

This is for:

Developer System Administrator

Assuming that you’ve created a secured Push source, along with a security identity provider for your secured Push source, you can then use the Push API to add a raw text item with access permissions to your source.

This article details the different components of a secured Push source and sample requests to add a secured item and its associated security identities.

Secured item

Request configuration

PUT https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/sources/mysourceidg3c5d1r2/documents?documentId=file%3A%2F%2Ffolder%2Fmytext.txt HTTP/1.1

Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

Request payload (see Item Models - DocumentBody)

{
  "author": "Alice Smith",
  "date": "2017-11-08T12:18:41.666Z",
  "documenttype": "Text",
  "filename": "mytext.txt",
  "language": [
    "English"
  ],
  "permanentid": "sample95829alice84720permanent93829id",
  "sourcetype": "Push",
  "title": "My Text",
  "fileExtension": ".txt",
  "data": "This is a sample text written by Alice Smith.",
  "permissions": [
    {
      "allowAnonymous": false,
      "allowedPermissions": [
        {
          "identity": "AlphaTeam",
          "identityType": "Group"
        }
      ],
      "deniedPermissions": [
        {
          "identity": "bob@example.com",
          "identityType": "User"
        }
      ]
    }
  ]
}

In the above example, several pieces of metadata are pushed along with the item (for example, author, date, and documenttype). This metadata will be mapped to corresponding fields in the index. For more details about the Push source metadata mapping process, see About Push source item metadata.

The data property contains the item body itself. There are other ways to push the body of an item, depending on your specific needs.

Finally, the item has a set of permissions. Specifying a permission model is necessary when adding an item to a secured Push source that doesn’t itself have a global permission model in its configuration. In this example, the item will be accessible by all security identities that are members of the AlphaTeam {group}, except user bob@example.com.

Security identity definition

You must define the security identities an item permission model refers to, so that allowed users will be able to access an item with access permissions in their query results. The following request defines the AlphaTeam group in the security identity provider which has been associated to the secured Push source.

Request configuration

PUT https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/providers/mysecurityidentityprovider8d9s8d/permissions HTTP/1.1

Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

Request payload (see Security Identity Models - IdentityBody)

{
  "identity": {
    "name": "AlphaTeam",
    "type": "GROUP"
  },
  "members": [
    {
      "name": "alice@example.com",
      "type": "USER"
    },
    {
      "name": "bob@example.com",
      "type": "USER"
    },
    {
      "name": "david@example.com",
      "type": "USER"
    }
  ]
}

Security identity to Email Security Provider user mapping

As things stand, the group members (that is, alice@example.com, bob@example.com, and david@example.com) wouldn’t be recognized by the provider. The recommended way to fix this is to create an alias relationship between each of those group members and the corresponding user in the Email Security Provider. In addition to allowing your provider to detect those users, doing so will allow those users to access content across many secured enterprise systems. The following request defines an alias for user alice@example.com. You would perform similar requests to define aliases for users bob@example.com, and david@example.com.

Request configuration

PUT https://api.cloud.coveo.com/push/v1/organizations/mycoveocloudv2organizationg8tp8wu3/providers/mysecurityidentityprovider8d9s8d/mappings HTTP/1.1

Content-Type: application/json
Authorization: Bearer **********-****-****-****-************

Request payload (see Security Identity Models - MappedIdentityBody)

{
  "Identity": {
    "Name": "alice@example.com",
    "Type": "USER"
    },
    "Mappings": [
      {
        "Name": "alice@example.com",
        "Type": "USER",
        "Provider": "Email Security Provider"
      }
    ]
}

Validating the push operations

After the Push API processing delay, you can validate the success of your push operations by navigating to the Content Browser (platform-ca | platform-eu | platform-au) of the Coveo Administration Console. The item should appear.

Image of the item in the Content Browser | Coveo

You can double-click the item to inspect its properties. In particular, you can validate the security identities. The image below shows that alice@example.com and david@example.com both have access to the item, while bob@example.com doesn’t, as expected. Moreover, you can see that the alias relationships for alice@example.com and david@example.com are functional, the access being granted under Email Security Provider as well as under mysecurityidentityprovider8d9s8d. In contrast, bob@example.com is denied access in both providers.

Permissions of the item in the Content Browser | Coveo

What’s next?

In this example, each item and security identity is pushed individually. However, the Push API also allows you to manage items and security identities in batches. A good way to learn about this feature is to do the third Push API tutorial.

The Push API tutorials can also introduce you to more advanced concepts, such as creating complex permission models and using custom mappings.